modusa 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

modusa/decorators.py

@@ -103,7 +103,7 @@ def validate_arg(arg_name: str, value: Any, expected_type: Any) -> None:
 		union_args = get_args(expected_type)
 		for typ in union_args:
 			typ_origin = get_origin(typ) or typ
-			if type(value) is typ_origin:
+			if isinstance(value, typ_origin):
 				return
 		
 		# ❌ If none match
@@ -116,17 +116,17 @@ def validate_arg(arg_name: str, value: Any, expected_type: Any) -> None:
 	
 	# Handle generic types like list[float], tuple[int, str]
 	elif origin is not None:
-		if type(value) is not origin:
+		if not isinstance(value, origin):
 			raise excp.ValidationError(
-				f"Argument '{arg_name}' must be exactly of type {origin.__name__}, got {type(value).__name__}"
+				f"Argument '{arg_name}' must be of type {origin.__name__}, got {type(value).__name__}"
 			)
 		return
 		
 	# ✅ Handle plain types
 	elif isinstance(expected_type, type):
-		if type(value) is not expected_type:
+		if not isinstance(value, expected_type):
 			raise excp.ValidationError(
-				f"Argument '{arg_name}' must be exactly {expected_type.__name__}, got {type(value).__name__}"
+				f"Argument '{arg_name}' must be of type {expected_type.__name__}, got {type(value).__name__}"
 			)
 		return
 	# ❌ Unsupported type structure

modusa/devtools/generate_template.py

@@ -6,26 +6,76 @@ import questionary
 import sys
 
 ROOT_DIR = Path(__file__).parents[3].resolve()
+SRC_CODE_DIR = ROOT_DIR / "src/modusa"
+TESTS_DIR = ROOT_DIR / "tests"
 TEMPLATES_DIR = ROOT_DIR / "src/modusa/devtools/templates"
 
+PLUGIN_INFO = {
+	"template_fp": TEMPLATES_DIR / "plugin.py",
+	"test_template_fp": TEMPLATES_DIR / "test.py",
+	"template_dump_dp": SRC_CODE_DIR / "plugins",
+	"test_template_dump_dp": TESTS_DIR / "test_plugins"
+}
+IO_INFO = {
+	"template_fp": TEMPLATES_DIR / "io.py",
+	"test_template_fp": TEMPLATES_DIR / "test.py",
+	"template_dump_dp": SRC_CODE_DIR / "io",
+	"test_template_dump_dp": TESTS_DIR / "test_io"
+}
+GENERATOR_INFO = {
+	"template_fp": TEMPLATES_DIR / "generator.py",
+	"test_template_fp": TEMPLATES_DIR / "test.py",
+	"template_dump_dp": SRC_CODE_DIR / "generators",
+	"test_template_dump_dp": TESTS_DIR / "test_generators"
+}
+SIGNAL_INFO = {
+	"template_fp": TEMPLATES_DIR / "signal.py",
+	"test_template_fp": TEMPLATES_DIR / "test.py",
+	"template_dump_dp": SRC_CODE_DIR / "signals",
+	"test_template_dump_dp": TESTS_DIR / "test_signals"
+}
+ENGINE_INFO = {
+	"template_fp": TEMPLATES_DIR / "engine.py",
+	"test_template_fp": TEMPLATES_DIR / "test.py",
+	"template_dump_dp": SRC_CODE_DIR / "engines",
+	"test_template_dump_dp": TESTS_DIR / "test_engines"
+}
+
+
 class TemplateGenerator():
 	"""
-	Generates template for `plugin`, `engine`, `signal`, `generator`.
+	Generates template for `plugin`, `engine`, `signal`, `generator` along with its corresponding `test` file
+	in the `tests` directory.
 	"""
 	
+	
 	@staticmethod
-	def ask_questions(for_what: str) -> dict:
+	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 == "generator": return GENERATOR_INFO
+	
+	@staticmethod
+	def ask_questions(for_what: str, path_info: dict) -> dict:
+		"""Asks question about the template to be generated."""
 		print("----------------------")
 		print(for_what.upper())
 		print("----------------------")
 		module_name = questionary.text("Module name (snake_case): ").ask()
+		
 		if module_name is None:
 			sys.exit(1)
-		if Path(f"src/modusa/{for_what}/{module_name}.py").exists():
+			
+		if not module_name.endswith(".py"): # Adding extension
+			module_name = module_name + ".py"
+		# Checking if the module name already exists in the dump directory
+		if (path_info["template_dump_dp"] / module_name).exists():
 			print(f"⚠️ File already exists, choose another name.")
 			sys.exit(1)
 		
-		class_name = questionary.text("Class name (CamelCase): ").ask()
+		class_name = questionary.text(f"Class name (CamelCase{for_what.capitalize()}): ").ask()
 		if class_name is None:
 			sys.exit(1)
 			
@@ -37,43 +87,58 @@ class TemplateGenerator():
 		if author_email is None:
 			sys.exit(1)
 		
-		answers = {"module_name": module_name, "class_name": class_name, "author_name": author_name, "author_email": author_email, "date_created": date.today()}
+		answers = {"for_what": for_what, "module_name": module_name, "class_name": class_name, "author_name": author_name, "author_email": author_email, "date_created": date.today()}
 			
 		return answers
 	
 	@staticmethod
-	def load_template_file(for_what: str) -> str:
-		template_path = TEMPLATES_DIR / f"{for_what}.py"
-		if not template_path.exists():
-			print(f"❌ Template not found: {template_path}")
+	def load_template_file(template_fp: Path) -> str:
+		"""Loads template file."""
+		if not template_fp.exists():
+			print(f"❌ Template not found: {template_fp}")
 			sys.exit(1)
 		
-		template_code = template_path.read_text()
+		template_code = template_fp.read_text()
 		
 		return template_code
 	
 	@staticmethod
 	def fill_placeholders(template_code: str, placehoders_dict: dict) -> str:
+		"""Fills placeholder in the template with the user input from CLI."""
 		template_code = template_code.format(**placehoders_dict)  # Fill placeholders
 		return template_code
 	
 	@staticmethod
 	def save_file(content: str, output_path: Path) -> None:
+		"""Saves file in the correct directory with the right tempalate content."""
 		output_path.parent.mkdir(parents=True, exist_ok=True)
 		output_path.write_text(content)
-		print(f"✅ Successfully created.\n\n open {output_path.resolve()}")
+		
+		# Generating a corresponding test file too
+		what_for = output_path.parent.name # plugins, generators, ...
+		module_name = output_path.name # this.py
+	
 	
 	@staticmethod
 	def create_template(for_what: str) -> None:
 		
+		# Load correct path location info for the templates and where to dump the files
+		path_info: dict = TemplateGenerator.get_path_info(for_what)
+		
 		# Ask basic questions to create the template for `plugin`, `generator`, ...
-		answers: dict = TemplateGenerator.ask_questions(for_what)
+		answers: dict = TemplateGenerator.ask_questions(for_what, path_info)
 		
-		# Load the correct template file
-		template_code: str = TemplateGenerator.load_template_file(for_what)
+		# Load the correct template file and test file
+		template_code: str = TemplateGenerator.load_template_file(template_fp=path_info['template_fp'])
+		test_code: str = TemplateGenerator.load_template_file(template_fp=path_info['test_template_fp'])
 		
 		# Update the dynamic values based on the answers
 		template_code: str = TemplateGenerator.fill_placeholders(template_code, answers)
+		test_code: str = TemplateGenerator.fill_placeholders(test_code, answers)
 		
 		# Save it to a file and put it in the correct folder
-		TemplateGenerator.save_file(content=template_code, output_path=ROOT_DIR / f"src/modusa/{for_what}/{answers['module_name']}.py")
+		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'])
+		
+		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']))

modusa/devtools/main.py

@@ -20,10 +20,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("engines"))
-		create_subparsers.add_parser("plugin", help="Create a new plugin class").set_defaults(func=lambda:TemplateGenerator.create_template("plugins"))
-		create_subparsers.add_parser("signal", help="Create a new signal class").set_defaults(func=lambda:TemplateGenerator.create_template("signals"))
-		create_subparsers.add_parser("generator", help="Create a new signal generator class").set_defaults(func=lambda:TemplateGenerator.create_template("generators"))
+		create_subparsers.add_parser("engine", help="Create a new engine class").set_defaults(func=lambda:TemplateGenerator.create_template("engine"))
+		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"))
+		
 		
 		# --- LIST group ---
 		list_parser = subparsers.add_parser("list", help="List information about Modusa components")

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

@@ -3,20 +3,21 @@
 
 from modusa import excp
 from modusa.decorators import validate_args_type
-from modusa.engines.base import ModusaEngine
+from modusa.engines import ModusaEngine
 from typing import Any
 
+
 class {class_name}(ModusaEngine):
 	"""
-
+	
 	"""
 	
 	#--------Meta Information----------
-	name = ""
-	description = ""
-	author_name = "{author_name}"
-	author_email = "{author_email}"
-	created_at = "{date_created}"
+	_name = ""
+	_description = ""
+	_author_name = "{author_name}"
+	_author_email = "{author_email}"
+	_created_at = "{date_created}"
 	#----------------------------------
 	
 	def __init__(self):

modusa/devtools/templates/{generators.py → generator.py}

@@ -1,8 +1,9 @@
 #!/usr/bin/env python3
 
 
+from modusa import excp
 from modusa.decorators import validate_args_type
-from modusa.generators.base import ModusaGenerator
+from modusa.generators import ModusaGenerator
 
 
 class {class_name}(ModusaGenerator):
@@ -11,16 +12,13 @@ class {class_name}(ModusaGenerator):
 	"""
 	
 	#--------Meta Information----------
-	name = ""
-	description = ""
-	author_name = "{author_name}"
-	author_email = "{author_email}"
-	created_at = "{date_created}"
+	_name = ""
+	_description = ""
+	_author_name = "{author_name}"
+	_author_email = "{author_email}"
+	_created_at = "{date_created}"
 	#----------------------------------
 	
 	def __init__(self):
 		super().__init__()
-	
-	
-	def generate(self) -> Any:
-		pass
+	

modusa/devtools/templates/io.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+
+
+from modusa import excp
+from modusa.decorators import validate_args_type
+from modusa.io import ModusaIO
+
+
+class {class_name}(ModusaIO):
+	"""
+
+	"""
+	
+	#--------Meta Information----------
+	_name = ""
+	_description = ""
+	_author_name = "{author_name}"
+	_author_email = "{author_email}"
+	_created_at = "{date_created}"
+	#----------------------------------
+	
+	
+
+	

modusa/devtools/templates/{plugins.py → plugin.py}

@@ -1,8 +1,9 @@
 #!/usr/bin/env python3
 
 
-from modusa.plugins.base import ModusaPlugin
+from modusa import excp
 from modusa.decorators import immutable_property, validate_args_type, plugin_safety_check
+from modusa.plugins import ModusaPlugin
 
 
 class {class_name}(ModusaPlugin):
@@ -11,11 +12,11 @@ class {class_name}(ModusaPlugin):
 	"""
 	
 	#--------Meta Information----------
-	name = ""
-	description = ""
-	author_name = "{author_name}"
-	author_email = "{author_email}"
-	created_at = "{date_created}"
+	_name = ""
+	_description = ""
+	_author_name = "{author_name}"
+	_author_email = "{author_email}"
+	_created_at = "{date_created}"
 	#----------------------------------
 	
 	def __init__(self):

modusa/devtools/templates/signal.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+
+
+from modusa import excp
+from modusa.decorators import immutable_property, validate_args_type
+from modusa.signals.base import ModusaSignal
+from typing import Self, Any
+import numpy as np
+
+class {class_name}(ModusaSignal):
+	"""
+
+	"""
+	
+	#--------Meta Information----------
+	_name = ""
+	_description = ""
+	_author_name = "{author_name}"
+	_author_email = "{author_email}"
+	_created_at = "{date_created}"
+	#----------------------------------
+	
+	@validate_args_type()
+	def __init__(self):
+		super().__init__() # Instantiating `ModusaSignal` class
+	
+		self.title = "" # This title will be used as plot title by default
+		
+	#----------------------
+	# Properties
+	#----------------------
+		
+	
+	
+	
+	
+	
+	#----------------------
+	# Tools
+	#----------------------

modusa/devtools/templates/test.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+
+
+#--------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/engines/__init__.py

@@ -1,4 +1,3 @@
 #!/usr/bin/env python3
 
-from .plot_1dsignal import Plot1DSignalEngine
-from .plot_2dmatrix import Plot2DMatrixEngine
+from .base import ModusaEngine

modusa/generators/__init__.py

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

modusa/generators/audio_waveforms.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+
+
+from modusa import excp
+from modusa.decorators import validate_args_type
+from modusa.generators import ModusaGenerator
+from modusa.signals import AudioSignal
+import numpy as np
+
+class AudioWaveformGenerator(ModusaGenerator):
+	"""
+
+	"""
+	
+	#--------Meta Information----------
+	_name = "Audio Waveform Generator"
+	_description = ""
+	_author_name = "Ankit Anand"
+	_author_email = "ankit0.anand0@gmail.com"
+	_created_at = "2025-07-07"
+	#----------------------------------
+	
+	@staticmethod
+	def generate_example() -> "AudioSignal":
+		"""
+		Generates a simple sine wave audio signal for demonstration purposes.
+	
+		Returns
+		-------
+		AudioSignal
+			A 600 Hz sine wave lasting 2 seconds, sampled at 10,000 Hz.
+		"""
+		
+		sr = 10000 # Hz
+		duration = 2 # sec
+		freq = 600 # Hz
+		
+		t = np.arange(0, duration, 1 / sr)
+		y = np.sin(2 * np.pi * freq * t)
+		
+		signal = AudioSignal(y=y, sr=sr, title="Example")  # assuming AudioSignal accepts y and t
+		
+		return signal
+	
+	
+	@staticmethod
+	def generate_random(duration: float = 1.0, sr: int = 10000) -> "AudioSignal":
+		"""
+		Generates a random audio signal of given duration and sample rate.
+	
+		Parameters
+		----------
+		duration : float, optional
+			Duration of the signal in seconds (default is 1.0).
+		sr : int, optional
+			Sampling rate in Hz (default is 10,000).
+	
+		Returns
+		-------
+		AudioSignal
+			A randomly generated signal of the specified duration and sample rate.
+		"""
+		num_samples = int(duration * sr)
+		t = np.linspace(0, duration, num=num_samples, endpoint=False)
+		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
+	@validate_args_type()
+	def generate_sinusoid(
+		A: float | int = 1.0,
+		f: float | int = 10.0,
+		phi: float | int = 0.0,
+		duration: float | int = 1.0,
+		sr: int = 1000,
+	) -> "AudioSignal":
+		"""
+		Generates a sinusoidal AudioSignal with specified amplitude, frequency, phase, duration, and sample rate.
+	
+		Parameters
+		----------
+		A : float
+			Amplitude of the sinusoid (default: 1.0)
+		f : float
+			Frequency in Hz (default: 10.0)
+		phi : float
+			Phase in radians (default: 0.0)
+		duration : float
+			Duration of the signal in seconds (default: 1.0)
+		sr : int
+			Sampling rate in Hz (default: 1000)
+	
+		Returns
+		-------
+		AudioSignal
+			A time-domain 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")
+		return signal
+	
+	@staticmethod
+	@validate_args_type()
+	def generate_square(
+		A: float | int = 1.0,
+		f: float | int = 10.0,
+		phi: float | int = 0.0,
+		duration: float | int = 1.0,
+		sr: int = 1000,
+	) -> "AudioSignal":
+		"""
+		Generates a square wave AudioSignal with specified amplitude, frequency, phase, duration, and sample rate.
+	
+		Parameters
+		----------
+		A : float
+			Amplitude of the square wave (default: 1.0)
+		f : float
+			Frequency in Hz (default: 10.0)
+		phi : float
+			Phase in radians (default: 0.0)
+		duration : float
+			Duration of the signal in seconds (default: 1.0)
+		sr : int
+			Sampling rate in Hz (default: 1000)
+	
+		Returns
+		-------
+		AudioSignal
+			A square wave signal of the specified 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.sign(np.sin(2 * np.pi * f * t + phi))
+		
+		signal = AudioSignal(y=y, sr=sr, title="Square")
+		return signal
+	
+	
+	@staticmethod
+	@validate_args_type()
+	def generate_sawtooth(
+		A: float | int = 1.0,
+		f: float | int = 10.0,
+		phi: float | int = 0.0,
+		duration: float | int = 1.0,
+		sr: int = 1000,
+	) -> "AudioSignal":
+		"""
+		Generates a sawtooth wave AudioSignal with specified amplitude, frequency, phase, duration, and sample rate.
+	
+		Parameters
+		----------
+		A : float
+			Amplitude of the sawtooth wave (default: 1.0)
+		f : float
+			Frequency in Hz (default: 10.0)
+		phi : float
+			Phase in radians (default: 0.0)
+		duration : float
+			Duration of the signal in seconds (default: 1.0)
+		sr : int
+			Sampling rate in Hz (default: 1000)
+	
+		Returns
+		-------
+		AudioSignal
+			A sawtooth wave signal of the specified parameters.
+		"""
+		A, f, phi, duration, sr = float(A), float(f), float(phi), float(duration), int(sr)
+		t = np.arange(0, duration, 1 / sr)
+		
+		# Convert phase from radians to fractional cycle offset
+		phase_offset = phi / (2 * np.pi)
+		y = A * (2 * ((f * t + phase_offset) % 1) - 1)
+		
+		signal = AudioSignal(y=y, sr=sr, title="Sawtooth")
+		return signal
+	
+	
+	@staticmethod
+	@validate_args_type()
+	def generate_triangle(
+		A: float | int = 1.0,
+		f: float | int = 10.0,
+		phi: float | int = 0.0,
+		duration: float | int = 1.0,
+		sr: int = 1000,
+	) -> "AudioSignal":
+		"""
+		Generates a triangle wave AudioSignal with specified amplitude, frequency, phase, duration, and sample rate.
+	
+		Parameters
+		----------
+		A : float
+			Amplitude of the triangle wave (default: 1.0)
+		f : float
+			Frequency in Hz (default: 10.0)
+		phi : float
+			Phase in radians (default: 0.0)
+		duration : float
+			Duration of the signal in seconds (default: 1.0)
+		sr : int
+			Sampling rate in Hz (default: 1000)
+	
+		Returns
+		-------
+		AudioSignal
+			A triangle wave signal of the specified parameters.
+		"""
+		A, f, phi, duration, sr = float(A), float(f), float(phi), float(duration), int(sr)
+		t = np.arange(0, duration, 1 / sr)
+		phase_offset = phi / (2 * np.pi)  # Convert radians to cycle offset
+		
+		# 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")
+		return signal
+	

modusa/generators/base.py

@@ -8,33 +8,22 @@ from typing import Any
 
 class ModusaGenerator(ABC):
 	"""
-	Base class for any generator.
+	Base class for any type of signal generators for modusa framework.
+	
+	Note
+	----
+	- This class is intended to be subclassed by any Generator related tools built for the modusa framework.
+	- In order to create a generator tool, you can use modusa-dev CLI to generate an generator template.
+	- It is recommended to treat subclasses of ModusaGenerator as namespaces and define @staticmethods with control parameters, rather than using instance-level __init__ methods.
+	
 	
-	Generates instance of different `ModusaSignal` subclass.
 	"""
 	
 	#--------Meta Information----------
-	name = ""
-	description = ""
-	author_name = "Ankit Anand"
-	author_email = "ankit0.anand0@gmail.com"
-	created_at = "2025-07-04"
+	_name = ""
+	_description = ""
+	_author_name = "Ankit Anand"
+	_author_email = "ankit0.anand0@gmail.com"
+	_created_at = "2025-07-04"
 	#----------------------------------
-	
-	def __init__(self, signal_cls: Any):
-		
-		if not issubclass(signal_cls, ModusaSignal):
-			raise excp.InputValueError(f"`signal_cls` must be a subclass of ModusaSignal, got {signal_cls.__name__}")
-		if signal_cls not in self.allowed_output_signal_types:
-			raise excp.InputValueError(f"`signal_cls` must be a one of the allowed types {self.allowed_output_signal_types}, got {signal_cls.__name__}") 
-
-		self._signal_cls = signal_cls
-	
-	@immutable_property("Mutation not allowed.")
-	def signal_cls(self) -> Any:
-		return self._signal_cls
-	
-	@property
-	@abstractmethod
-	def allowed_output_signal_types(self) -> tuple[type, ...]:
-		return
+	

modusa/io/__init__.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+
+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