modusa 0.2.21__py3-none-any.whl → 0.2.23__py3-none-any.whl

modusa/decorators.py

@@ -110,14 +110,14 @@ def validate_arg(arg_name: str, value: Any, expected_type: Any) -> None:
 		expected_names = ", ".join(
 			get_origin(t).__name__ if get_origin(t) else t.__name__ for t in union_args
 		)
-		raise excp.ValidationError(
+		raise excp.InputTypeError(
 			f"Argument '{arg_name}' must be one of ({expected_names}), got {type(value).__name__}"
 		)
 	
 	# Handle generic types like list[float], tuple[int, str]
 	elif origin is not None:
 		if not isinstance(value, origin):
-			raise excp.ValidationError(
+			raise excp.InputTypeError(
 				f"Argument '{arg_name}' must be of type {origin.__name__}, got {type(value).__name__}"
 			)
 		return
@@ -125,13 +125,13 @@ def validate_arg(arg_name: str, value: Any, expected_type: Any) -> None:
 	# ✅ Handle plain types
 	elif isinstance(expected_type, type):
 		if not isinstance(value, expected_type):
-			raise excp.ValidationError(
+			raise excp.InputTypeError(
 				f"Argument '{arg_name}' must be of type {expected_type.__name__}, got {type(value).__name__}"
 			)
 		return
 	# ❌ Unsupported type structure
 	else:
-		raise excp.ValidationError(f"Unsupported annotation for '{arg_name}': {expected_type}")
+		raise excp.InputTypeError(f"Unsupported annotation for '{arg_name}': {expected_type}")
 
 def validate_args_type() -> Callable:
 	def decorator(func: Callable) -> Callable:

modusa/devtools/docs/source/generators/audio_waveforms.rst

@@ -0,0 +1,8 @@
+AudioWaveformGenerator
+======================
+
+.. autoclass:: modusa.generators.audio_waveforms.AudioWaveformGenerator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/docs/source/generators/base.rst

@@ -0,0 +1,8 @@
+ModusaGenerator
+===============
+
+.. autoclass:: modusa.generators.base.ModusaGenerator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/docs/source/generators/index.rst

@@ -0,0 +1,8 @@
+Generators
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   base
+   audio_waveforms

modusa/devtools/docs/source/io/audio_loader.rst

@@ -0,0 +1,8 @@
+AudioLoader
+===========
+
+.. autoclass:: modusa.io.audio_loader.AudioLoader
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/docs/source/io/base.rst

@@ -0,0 +1,8 @@
+ModusaIO
+========
+
+.. autoclass:: modusa.io.base.ModusaIO
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/docs/source/io/index.rst

@@ -0,0 +1,8 @@
+IO
+==
+
+.. toctree::
+   :maxdepth: 1
+
+   base
+   audio_loader

modusa/devtools/docs/source/plugins/base.rst

@@ -0,0 +1,8 @@
+ModusaPlugin
+============
+
+.. autoclass:: modusa.plugins.base.ModusaPlugin
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/docs/source/plugins/index.rst

@@ -0,0 +1,7 @@
+Plugins
+=======
+
+.. toctree::
+   :maxdepth: 1
+
+   base

modusa/devtools/docs/source/signals/audio_signal.rst

@@ -0,0 +1,8 @@
+AudioSignal
+===========
+
+.. autoclass:: modusa.signals.audio_signal.AudioSignal
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/docs/source/signals/base.rst

@@ -0,0 +1,8 @@
+ModusaSignal
+============
+
+.. autoclass:: modusa.signals.base.ModusaSignal
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/docs/source/signals/frequency_domain_signal.rst

@@ -0,0 +1,8 @@
+FrequencyDomainSignal
+=====================
+
+.. autoclass:: modusa.signals.frequency_domain_signal.FrequencyDomainSignal
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/docs/source/signals/index.rst

@@ -0,0 +1,11 @@
+Signals
+=======
+
+.. toctree::
+   :maxdepth: 1
+
+   base
+   audio_signal
+   frequency_domain_signal
+   spectrogram
+   time_domain_signal

modusa/devtools/docs/source/signals/spectrogram.rst

@@ -0,0 +1,8 @@
+Spectrogram
+===========
+
+.. autoclass:: modusa.signals.spectrogram.Spectrogram
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/docs/source/signals/time_domain_signal.rst

@@ -0,0 +1,8 @@
+TimeDomainSignal
+================
+
+.. autoclass:: modusa.signals.time_domain_signal.TimeDomainSignal
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/docs/source/tools/audio_converter.rst

@@ -0,0 +1,8 @@
+AudioConverter
+==============
+
+.. autoclass:: modusa.tools.audio_converter.AudioConverter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/docs/source/tools/audio_player.rst

@@ -0,0 +1,8 @@
+AudioPlayer
+===========
+
+.. autoclass:: modusa.tools.audio_player.AudioPlayer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/docs/source/tools/base.rst

@@ -0,0 +1,8 @@
+ModusaTool
+==========
+
+.. autoclass:: modusa.tools.base.ModusaTool
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/docs/source/tools/fourier_tranform.rst

@@ -0,0 +1,8 @@
+FourierTransform
+================
+
+.. autoclass:: modusa.tools.fourier_tranform.FourierTransform
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/docs/source/tools/index.rst

@@ -0,0 +1,13 @@
+Tools
+=====
+
+.. toctree::
+   :maxdepth: 1
+
+   base
+   audio_converter
+   audio_player
+   fourier_tranform
+   math_ops
+   plotter
+   youtube_downloader

modusa/devtools/docs/source/tools/math_ops.rst

@@ -0,0 +1,8 @@
+MathOps
+=======
+
+.. autoclass:: modusa.tools.math_ops.MathOps
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/docs/source/tools/plotter.rst

@@ -0,0 +1,8 @@
+Plotter
+=======
+
+.. autoclass:: modusa.tools.plotter.Plotter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/docs/source/tools/youtube_downloader.rst

@@ -0,0 +1,8 @@
+YoutubeDownloader
+=================
+
+.. autoclass:: modusa.tools.youtube_downloader.YoutubeDownloader
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

modusa/devtools/generate_doc_source.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+
+import inspect
+import importlib
+import pkgutil
+from pathlib import Path
+from collections import defaultdict
+
+# === Configuration ===
+BASE_MODULES = [
+    'modusa.tools',
+    'modusa.signals',
+    'modusa.generators',
+    'modusa.plugins',
+    'modusa.io'
+]
+OUTPUT_DIRS = [
+    Path('docs/source/tools'),
+    Path('docs/source/signals'),
+    Path('docs/source/generators'),
+    Path('docs/source/plugins'),
+    Path('docs/source/io')
+]
+
+# Ensure output directories exist
+for output_dir in OUTPUT_DIRS:
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+# === Utils ===
+def get_classes_grouped_by_module(base_module):
+    """
+    Returns a dictionary: { module_path: [class_name, ...] }
+    """
+    found = defaultdict(list)
+    module = importlib.import_module(base_module)
+
+    for _, modname, _ in pkgutil.walk_packages(module.__path__, base_module + "."):
+        try:
+            submodule = importlib.import_module(modname)
+            for name, obj in inspect.getmembers(submodule, inspect.isclass):
+                if obj.__module__ == modname:
+                    found[modname].append(name)
+        except Exception as e:
+            print(f"⚠️ Skipping {modname} due to import error: {e}")
+    return found
+
+def write_module_rst_file(module_path, class_names, output_dir):
+    """
+    Writes a .rst file for a module, documenting all its classes.
+    Filename is based on the module, but title is the first class (Modusa* gets priority).
+    """
+    filename = output_dir / f"{module_path.split('.')[-1]}.rst"
+
+    # Prioritize 'Modusa*' classes first, then alphabetical
+    sorted_classes = sorted(class_names, key=lambda x: (not x.startswith("Modusa"), x.lower()))
+    title = sorted_classes[0] if sorted_classes else module_path.split('.')[-1]
+
+    with open(filename, 'w') as f:
+        f.write(f"{title}\n{'=' * len(title)}\n\n")
+        for class_name in sorted_classes:
+            f.write(f".. autoclass:: {module_path}.{class_name}\n")
+            f.write("   :members:\n")
+            f.write("   :undoc-members:\n")
+            f.write("   :show-inheritance:\n\n")
+    
+    return filename.name
+
+def write_index_rst_file(tools_by_module, output_dir, section_name="Tools"):
+    """
+    Writes index.rst in the given output_dir with 'base' on top, then other files alphabetically.
+    """
+    index_file = output_dir / "index.rst"
+    with open(index_file, "w") as f:
+        f.write(f"{section_name}\n{'=' * len(section_name)}\n\n")
+        f.write(".. toctree::\n   :maxdepth: 1\n\n")
+
+        filenames = [module_path.split('.')[-1] for module_path in tools_by_module]
+        sorted_filenames = sorted(filenames, key=lambda x: (x != "base", x.lower()))
+
+        for name in sorted_filenames:
+            f.write(f"   {name}\n")
+
+# === Main Script ===
+def generate_doc_source():
+    for base_module, output_dir in zip(BASE_MODULES, OUTPUT_DIRS):
+        module_class_map = get_classes_grouped_by_module(base_module)
+    
+        for module_path, class_list in module_class_map.items():
+            write_module_rst_file(module_path, class_list, output_dir)
+    
+        section_name = base_module.split('.')[-1].capitalize()
+        if section_name == "Io":
+            section_name = "IO"
+    
+        write_index_rst_file(module_class_map, output_dir, section_name=section_name)
+        print(f"✅ Documentation generated for {base_module} in {output_dir}")

modusa/devtools/generate_template.py

@@ -34,11 +34,11 @@ SIGNAL_INFO = {
 	"template_dump_dp": SRC_CODE_DIR / "signals",
 	"test_template_dump_dp": TESTS_DIR / "test_signals"
 }
-ENGINE_INFO = {
-	"template_fp": TEMPLATES_DIR / "engine.py",
+TOOL_INFO = {
+	"template_fp": TEMPLATES_DIR / "tool.py",
 	"test_template_fp": TEMPLATES_DIR / "test.py",
-	"template_dump_dp": SRC_CODE_DIR / "engines",
-	"test_template_dump_dp": TESTS_DIR / "test_engines"
+	"template_dump_dp": SRC_CODE_DIR / "tools",
+	"test_template_dump_dp": TESTS_DIR / "test_tools"
 }
 
 
@@ -54,7 +54,7 @@ class TemplateGenerator():
 		if for_what == "plugin": return PLUGIN_INFO
 		if for_what == "io": return IO_INFO
 		if for_what == "signal": return SIGNAL_INFO
-		if for_what == "engine": return ENGINE_INFO
+		if for_what == "tool": return TOOL_INFO
 		if for_what == "generator": return GENERATOR_INFO
 	
 	@staticmethod
@@ -75,7 +75,7 @@ class TemplateGenerator():
 			print(f"⚠️ File already exists, choose another name.")
 			sys.exit(1)
 		
-		class_name = questionary.text(f"Class name (CamelCase{for_what.capitalize()}): ").ask()
+		class_name = questionary.text(f"Class name (CamelCase): ").ask()
 		if class_name is None:
 			sys.exit(1)
 			
@@ -138,7 +138,7 @@ class TemplateGenerator():
 		
 		# Save it to a file and put it in the correct folder
 		TemplateGenerator.save_file(content=template_code, output_path=path_info['template_dump_dp'] / answers['module_name'])
-		TemplateGenerator.save_file(content=test_code, output_path=path_info['test_template_dump_dp'] / answers['module_name'])
+		TemplateGenerator.save_file(content=test_code, output_path=path_info['test_template_dump_dp'] / f"test_{answers['module_name']}")
 		
 		print(f"✅ {for_what}:", "open " + str(path_info['template_dump_dp'] / answers['module_name']))
-		print(f"✅ test:", "open " + str(path_info['test_template_dump_dp'] / answers['module_name']))
+		print(f"✅ test:", "open " + str(path_info['test_template_dump_dp'] / f"test_{answers['module_name']}"))

modusa/devtools/main.py

@@ -2,6 +2,7 @@
 
 
 from .generate_template import TemplateGenerator
+from .generate_doc_source import generate_doc_source
 from .list_plugins import list_plugins
 from . import list_authors
 
@@ -20,12 +21,12 @@ def main():
 		create_parser = subparsers.add_parser("create", help="Create new Modusa components")
 		create_subparsers = create_parser.add_subparsers(dest="what", required=True)
 		
-		create_subparsers.add_parser("engine", help="Create a new engine class").set_defaults(func=lambda:TemplateGenerator.create_template("engine"))
+		create_subparsers.add_parser("tool", help="Create a new tool class").set_defaults(func=lambda:TemplateGenerator.create_template("tool"))
 		create_subparsers.add_parser("plugin", help="Create a new plugin class").set_defaults(func=lambda:TemplateGenerator.create_template("plugin"))
 		create_subparsers.add_parser("signal", help="Create a new signal class").set_defaults(func=lambda:TemplateGenerator.create_template("signal"))
 		create_subparsers.add_parser("generator", help="Create a new signal generator class").set_defaults(func=lambda:TemplateGenerator.create_template("generator"))
 		create_subparsers.add_parser("io", help="Create a new IO class").set_defaults(func=lambda:TemplateGenerator.create_template("io"))
-		
+		create_subparsers.add_parser("doc", help="Create a new IO class").set_defaults(func=lambda:generate_doc_source())
 		
 		# --- LIST group ---
 		list_parser = subparsers.add_parser("list", help="List information about Modusa components")

modusa/devtools/templates/test.py

@@ -1,11 +1,10 @@
 #!/usr/bin/env python3
 
+from modusa import excp
 
 #--------Meta Information----------
 _class_name = "{class_name}"
 _author_name = "{author_name}"
 _author_email = "{author_email}"
 _created_at = "{date_created}"
-#----------------------------------
-	
-from modusa.{for_what}s import {class_name}
+#----------------------------------

modusa/devtools/templates/{engine.py → tool.py}

@@ -3,11 +3,10 @@
 
 from modusa import excp
 from modusa.decorators import validate_args_type
-from modusa.engines import ModusaEngine
-from typing import Any
+from modusa.tools.base import ModusaTool
 
 
-class {class_name}(ModusaEngine):
+class {class_name}(ModusaTool):
 	"""
 	
 	"""
@@ -22,8 +21,4 @@ class {class_name}(ModusaEngine):
 	
 	def __init__(self):
 		super().__init__()
-	
-	
-	@validate_args_type()
-	def run(self) -> Any:
-		pass
+	

modusa/generators/__init__.py

@@ -1,5 +1,3 @@
 #!/usr/bin/env python3
 
-from .base import ModusaGenerator
-
 from .audio_waveforms import AudioWaveformGenerator

modusa/generators/audio_waveforms.py

@@ -3,18 +3,20 @@
 
 from modusa import excp
 from modusa.decorators import validate_args_type
-from modusa.generators import ModusaGenerator
-from modusa.signals import AudioSignal
+from modusa.generators.base import ModusaGenerator
+from modusa.signals.audio_signal import AudioSignal
 import numpy as np
 
 class AudioWaveformGenerator(ModusaGenerator):
 	"""
-
+	Generates different kinds of audio waveforms particulary helpful
+	in teaching signal processing concepts and testing out newly
+	created tools.
 	"""
 	
 	#--------Meta Information----------
 	_name = "Audio Waveform Generator"
-	_description = ""
+	_description = "Generates different kind of audio waveforms."
 	_author_name = "Ankit Anand"
 	_author_email = "ankit0.anand0@gmail.com"
 	_created_at = "2025-07-07"
@@ -23,7 +25,7 @@ class AudioWaveformGenerator(ModusaGenerator):
 	@staticmethod
 	def generate_example() -> "AudioSignal":
 		"""
-		Generates a simple sine wave audio signal for demonstration purposes.
+		Generates a simple sine wave audio signal as an example.
 	
 		Returns
 		-------
@@ -65,6 +67,7 @@ class AudioWaveformGenerator(ModusaGenerator):
 		y = np.random.uniform(low=-1.0, high=1.0, size=num_samples)  # use uniform [-1, 1] for audio-like signal
 		
 		signal = AudioSignal(y=y, t=t, title="Random")
+		
 		return signal
 	
 	@staticmethod
@@ -77,7 +80,8 @@ class AudioWaveformGenerator(ModusaGenerator):
 		sr: int = 1000,
 	) -> "AudioSignal":
 		"""
-		Generates a sinusoidal AudioSignal with specified amplitude, frequency, phase, duration, and sample rate.
+		Generates a sinusoid audio signal with specified
+		amplitude, frequency, phase, duration, and sample rate.
 	
 		Parameters
 		----------
@@ -95,14 +99,15 @@ class AudioWaveformGenerator(ModusaGenerator):
 		Returns
 		-------
 		AudioSignal
-			A time-domain sinusoidal signal with the given parameters.
+			A sinusoidal signal with the given parameters.
 		"""
 		A, f, phi, duration, sr = float(A), float(f), float(phi), float(duration), int(sr)
 		
 		t = np.arange(0, duration, 1 / sr)
 		y = A * np.sin(2 * np.pi * f * t + phi)
 		
-		signal = AudioSignal(y=y, sr=sr, title="Sinusoid")
+		signal = AudioSignal(y=y, sr=sr, title=f"Sinusoid ({f} Hz)")
+		
 		return signal
 	
 	@staticmethod
@@ -115,7 +120,8 @@ class AudioWaveformGenerator(ModusaGenerator):
 		sr: int = 1000,
 	) -> "AudioSignal":
 		"""
-		Generates a square wave AudioSignal with specified amplitude, frequency, phase, duration, and sample rate.
+		Generates a square wave audio signal with specified
+		amplitude, frequency, phase, duration, and sample rate.
 	
 		Parameters
 		----------
@@ -140,7 +146,8 @@ class AudioWaveformGenerator(ModusaGenerator):
 		
 		y = A * np.sign(np.sin(2 * np.pi * f * t + phi))
 		
-		signal = AudioSignal(y=y, sr=sr, title="Square")
+		signal = AudioSignal(y=y, sr=sr, title=f"Square ({f} Hz)")
+		
 		return signal
 	
 	
@@ -181,7 +188,7 @@ class AudioWaveformGenerator(ModusaGenerator):
 		phase_offset = phi / (2 * np.pi)
 		y = A * (2 * ((f * t + phase_offset) % 1) - 1)
 		
-		signal = AudioSignal(y=y, sr=sr, title="Sawtooth")
+		signal = AudioSignal(y=y, sr=sr, title=f"Sawtooth ({f} Hz)")
 		return signal
 	
 	
@@ -195,7 +202,8 @@ class AudioWaveformGenerator(ModusaGenerator):
 		sr: int = 1000,
 	) -> "AudioSignal":
 		"""
-		Generates a triangle wave AudioSignal with specified amplitude, frequency, phase, duration, and sample rate.
+		Generates a triangle wave AudioSignal with specified
+		amplitude, frequency, phase, duration, and sample rate.
 	
 		Parameters
 		----------
@@ -222,6 +230,7 @@ class AudioWaveformGenerator(ModusaGenerator):
 		# Triangle wave formula: 2 * abs(2 * frac(x) - 1) - 1 scaled to amplitude
 		y = A * (2 * np.abs(2 * ((f * t + phase_offset) % 1) - 1) - 1)
 		
-		signal = AudioSignal(y=y, sr=sr, title="Triangle")
+		signal = AudioSignal(y=y, sr=sr, title=f"Triangle ({f} Hz)")
+		
 		return signal
 	

modusa/generators/base.py

@@ -2,7 +2,7 @@
 
 from modusa import excp
 from modusa.decorators import validate_args_type, immutable_property
-from modusa.signals import ModusaSignal
+from modusa.signals.base import ModusaSignal
 from abc import ABC, abstractmethod
 from typing import Any
 

modusa/io/__init__.py

@@ -2,8 +2,4 @@
 
 from .base import ModusaIO
 
-from .audio_loader import AudioLoader
-from .audio_converter import AudioConverter
-from .youtube_downloader import YoutubeDownloader
-from .plotter import Plotter
-from .audio_player import AudioPlayer
+from .audio_loader import AudioLoader

modusa/io/audio_loader.py

@@ -59,7 +59,8 @@ class AudioLoader(ModusaIO):
 			`Audio signal` instance with loaded audio content from YouTube.
 		"""
 
-		from modusa.io import YoutubeDownloader, AudioConverter
+		from modusa.tools.youtube_downloader import YoutubeDownloader
+		from modusa.tools.audio_converter import AudioConverter
 		import librosa
 		
 		# Download the audio in temp directory using tempfile module
@@ -115,41 +116,10 @@ class AudioLoader(ModusaIO):
 		audio_signal = AudioSignal(y=y, sr=sr, title=fp.name)
 		
 		return audio_signal
-	
-	
-	@staticmethod
-	def from_array(y: np.ndarray, t: np.ndarray | None = None) -> AudioSignal:
-		"""
-		Loads audio from numpy arrays.
-
-		.. code-block:: python
-			
-			from modusa.io import AudioSignalLoader
-			import numpy as np
-			
-			# From numpy array
-			audio_signal = AudioSignalLoader.from_array(
-				x=np.random.random((100, )),
-				t = None # Automatically creates time index (integer)
-			)
 
-		Parameters
-		----------
-		y: np.ndarray
-			Data of the audio signal.
-		t: np.ndarray | None
-			Corresponding time stamps of the audio signal.
-		
-		Returns
-		-------
-		AudioSignal
-			`Audio signal` instance with loaded audio content from arrays.
-		"""
-		
-		return  AudioSignal(y=y, t=t)
 	
 	@staticmethod
-	def from_array_with_sr(y: np.ndarray, sr: int) -> AudioSignal:
+	def from_array(y: np.ndarray, sr: int) -> AudioSignal:
 		"""
 		Loads audio with a given sampling rate.