modusa 0.2.22__py3-none-any.whl → 0.3__py3-none-any.whl

modusa/__init__.py

@@ -1 +1,8 @@
-from modusa.utils import excp, config
+from modusa.utils import excp, config
+
+#=====Giving access to plot functions to plot multiple signals.=====
+from modusa.tools import plot1d, plot2d
+from modusa.tools import play, convert
+from modusa.tools import download
+from modusa.tools import load
+#=====

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/generate_docs_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.models',
+    'modusa.generators',
+    'modusa.plugins',
+#   'modusa.io'
+]
+OUTPUT_DIRS = [
+    Path('docs/source/tools'),
+    Path('docs/source/models'),
+    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_docs_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

@@ -28,17 +28,17 @@ GENERATOR_INFO = {
 	"template_dump_dp": SRC_CODE_DIR / "generators",
 	"test_template_dump_dp": TESTS_DIR / "test_generators"
 }
-SIGNAL_INFO = {
-	"template_fp": TEMPLATES_DIR / "signal.py",
+MODEL_INFO = {
+	"template_fp": TEMPLATES_DIR / "model.py",
 	"test_template_fp": TEMPLATES_DIR / "test.py",
-	"template_dump_dp": SRC_CODE_DIR / "signals",
-	"test_template_dump_dp": TESTS_DIR / "test_signals"
+	"template_dump_dp": SRC_CODE_DIR / "models",
+	"test_template_dump_dp": TESTS_DIR / "test_models"
 }
-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"
 }
 
 
@@ -53,8 +53,8 @@ class TemplateGenerator():
 	def get_path_info(for_what: str):
 		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 == "model": return MODEL_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_docs_source import generate_docs_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("model", help="Create a new model class").set_defaults(func=lambda:TemplateGenerator.create_template("model"))
 		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("docs", help="Generate the docs").set_defaults(func=lambda:generate_docs_source())
 		
 		# --- LIST group ---
 		list_parser = subparsers.add_parser("list", help="List information about Modusa components")

modusa/devtools/templates/generator.py

@@ -3,7 +3,7 @@
 
 from modusa import excp
 from modusa.decorators import validate_args_type
-from modusa.generators import ModusaGenerator
+from modusa.generators.base import ModusaGenerator
 
 
 class {class_name}(ModusaGenerator):

modusa/devtools/templates/io.py

@@ -3,7 +3,7 @@
 
 from modusa import excp
 from modusa.decorators import validate_args_type
-from modusa.io import ModusaIO
+from modusa.io.base import ModusaIO
 
 
 class {class_name}(ModusaIO):

modusa/devtools/templates/{signal.py → model.py}

@@ -3,17 +3,18 @@
 
 from modusa import excp
 from modusa.decorators import immutable_property, validate_args_type
-from modusa.signals.base import ModusaSignal
+from modusa.signals.base import ?
 from typing import Self, Any
 import numpy as np
 
-class {class_name}(ModusaSignal):
+class {class_name}():
 	"""
 
 	"""
 	
 	#--------Meta Information----------
 	_name = ""
+	_nickname = "" # This is to be used in repr/str methods
 	_description = ""
 	_author_name = "{author_name}"
 	_author_email = "{author_email}"
@@ -26,15 +27,21 @@ class {class_name}(ModusaSignal):
 	
 		self.title = "" # This title will be used as plot title by default
 		
-	#----------------------
+	#-----------------------------------
 	# Properties
-	#----------------------
+	#-----------------------------------
 		
-	
-	
-	
-	
-	
-	#----------------------
+		
+	#===================================
+		
+		
+		
+		
+		
+		
+	#-----------------------------------
 	# Tools
-	#----------------------
+	#-----------------------------------
+		
+		
+	#===================================

modusa/devtools/templates/plugin.py

@@ -3,7 +3,7 @@
 
 from modusa import excp
 from modusa.decorators import immutable_property, validate_args_type, plugin_safety_check
-from modusa.plugins import ModusaPlugin
+from modusa.plugins.base import ModusaPlugin
 
 
 class {class_name}(ModusaPlugin):

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

@@ -2,4 +2,12 @@
 
 from .base import ModusaGenerator
 
-from .audio_waveforms import AudioWaveformGenerator
+from .s_ax import SAxGen
+from .t_ax import TAxGen
+
+from .s1d import S1DGen
+from .tds import TDSGen
+from .audio import AudioGen
+
+from .s2d import S2DGen
+from .ftds import FTDSGen

modusa/generators/audio.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+
+
+from modusa import excp
+from modusa.decorators import validate_args_type
+from .base import ModusaGenerator
+from modusa.models.t_ax import TAx
+from modusa.models.audio import Audio
+from modusa.models.data import Data
+import numpy as np
+from pathlib import Path
+
+class AudioGen(ModusaGenerator):
+	"""
+	Provides user friendly APIs to generate instances of different 
+	`AudioSignal` instances.
+	"""
+	
+	#--------Meta Information----------
+	_name = ""
+	_description = ""
+	_author_name = "Ankit Anand"
+	_author_email = "ankit0.anand0@gmail.com"
+	_created_at = "2025-07-27"
+	#----------------------------------
+	
+	@staticmethod
+	def from_array(
+		y: np.ndarray,
+		sr: float | int = 1.0,
+		t0: float | int = 0.0,
+		y_label: str = "Amplitude",
+		t_label: str = "Time (sec)",
+		title: str = "Audio Signal"
+	) -> Audio:
+		"""
+		Create `AudioSignal` instance from basic data structures.
+
+		.. code-block:: python
+
+			import modusa as ms
+			t = ms.tds.from_array([1, 2, 3])
+			print(t)
+			t.print_info()
+		
+		Parameters
+		----------
+		y: np.ndarray
+			- Audio data array.
+		sr: float | int
+			- Sampling rate.
+		t0: float | int
+			- Start timestamp.
+		y_label: str
+			- Y label for the signal.
+			- Default: "Y"
+		t_label: str
+			- T label for the signal.
+			- Default: "Time (sec)"
+		title: str
+			- Title for the signal.
+			- Default: "1D Signal"
+		Returns
+		-------
+		Audio
+			An instance of Audio.
+		"""
+		assert isinstance(y, np.ndarray)
+		assert isinstance(sr, (int, float)) and isinstance(t0, (int, float))
+		assert isinstance(y_label, str) and isinstance(t_label, str) and isinstance(title, str)
+		
+		assert y.ndim == 1
+		
+		sr = float(sr)
+		t0 = float(t0)
+		
+		t = TAx(n_points=y.shape[0], sr=sr, t0=t0, label=t_label) # Creating a signal axis instance
+		y = Data(values=y, label=y_label)
+		
+		return Audio(y=y, t=t, title=title)
+	
+	@classmethod
+	def from_youtube(cls, url: str, sr: int | float = None):
+		"""
+		Loads audio from youtube at a given sr.
+		The audio is deleted from the device
+		after loading.
+		
+		.. code-block:: python
+			
+			import modusa as ms
+			audio = ms.audio.from_youtube(
+				url="https://www.youtube.com/watch?v=lIpw9-Y_N0g", 
+				sr=None
+			)
+
+		PARAMETERS
+		----------
+		url: str
+			Link to the YouTube video.
+		sr: int
+			Sampling rate to load the audio in.
+		
+		Returns
+		-------
+		Audio:
+			An `Audio` instance with loaded audio content from YouTube.
+		"""
+		
+		from modusa.tools.youtube_downloader import YoutubeDownloader
+		from modusa import convert
+		import soundfile as sf
+		from scipy.signal import resample
+		import tempfile
+		
+		# Download the audio in temp directory using tempfile module
+		with tempfile.TemporaryDirectory() as tmpdir:
+			audio_fp: Path = YoutubeDownloader.download(url=url, content_type="audio", output_dir=Path(tmpdir))
+			
+			# Convert the audio to ".wav" form for loading
+			wav_audio_fp: Path = convert(inp_audio_fp=audio_fp, output_audio_fp=audio_fp.with_suffix(".wav"))
+			
+			# Load the audio in memory
+			audio_data, audio_sr = sf.read(wav_audio_fp)
+			
+			# Convert to mono if it's multi-channel
+			if audio_data.ndim > 1:
+				audio_data = audio_data.mean(axis=1)
+				
+			# Resample if needed
+			if sr is not None:
+				if audio_sr != sr:
+					n_samples = int(len(audio_data) * sr / audio_sr)
+					audio_data = resample(audio_data, n_samples)
+					audio_sr = sr
+					
+		audio = cls.from_array(y=audio_data, sr=audio_sr, title=audio_fp.stem)
+		
+		return audio
+	
+	@classmethod
+	def from_filepath(cls, fp: str | Path, sr: int | float = None):
+		"""
+		Loads audio from filepath at a given sr.
+		
+		.. code-block:: python
+			
+			import modusa as ms
+			audio = ms.audio.from_filepath(
+				fp="path/to/audio.wav",
+				sr=None
+			)
+
+		PARAMETERS
+		----------
+		fp: str | Path
+			Audio file path.
+		sr: int
+			Sampling rate to load the audio in.
+		
+		Returns
+		-------
+		Audio:
+			An `Audio` instance with loaded audio content.
+		"""
+		import soundfile as sf
+		from scipy.signal import resample
+		from pathlib import Path
+		
+		fp = Path(fp)
+		# Load the audio in memory
+		audio_data, audio_sr = sf.read(fp)
+		
+		# Convert to mono if it's multi-channel
+		if audio_data.ndim > 1:
+			audio_data = audio_data.mean(axis=1)
+			
+		# Resample if needed
+		if sr is not None:
+			if audio_sr != sr:
+				n_samples = int(len(audio_data) * sr / audio_sr)
+				audio_data = resample(audio_data, n_samples)
+				audio_sr = sr
+				
+		audio = cls.from_array(y=audio_data, sr=audio_sr, title=fp.stem)
+		
+		return audio
+	

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.models.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.models.base import ModusaSignal
 from abc import ABC, abstractmethod
 from typing import Any