Cleanup and refactor

CONTRIBUTING.md

@@ -90,6 +90,10 @@ with spaces on your end and have `git` automatically perform the conversion to
 tabs. You might want to use `ruff` instead of `expand` for a cross-platform
 solution that will also apply the rest of the project styling on commit!
 
+Note also that, when writing docstrings, it is preferred to put the first line
+of documentation on the line *below* the opening quotes, rather than on the same
+line.
+
 We use [Ruff](https://docs.astral.sh/ruff/) for code linting and formatting. To
 check your code, run `ruff check`. To automatically format your code, run `ruff
 format`. Note that certain rules are relaxed for test cases (for example,
@@ -134,7 +138,7 @@ our test code can be found in the [`test`](blob/main/test) directory.
 We ask that you try to maximize test coverage of any code that you contribute.
 We use [Codecov](https://about.codecov.io/) to calculate coverage percentage for
 commits and pull requests. You can check the coverage locally using pytest:
-`python -m pytest test --cov-report xml:cov.xml --cov modules`
+`python -m pytest test --cov-report xml --cov exseos`
 
 This will generate an XML coverage report, which can be read by several IDE
 extensions (for example, [Coverage

environment.yml

@@ -1,6 +1,7 @@
 name: exseos-h
 channels:
   - conda-forge
+  - nodefaults
 dependencies:
   - python=3.12
   - patch

modules/args/ArgumentProvider.py → exseos/args/ArgumentProvider.py

@@ -1,5 +1,5 @@
 """
-Chicory ML Workflow Manager
+ExSeOS-H Hardware ML Workflow Manager
 Copyright (C) 2024  Alexis Maya-Isabelle Shuping
 
 This program is free software: you can redistribute it and/or modify

modules/data/Variable.py → exseos/data/Variable.py

@@ -1,5 +1,5 @@
 """
-Chicory ML Workflow Manager
+ExSeOS-HLS Hardware ML Workflow Manager
 Copyright (C) 2024  Alexis Maya-Isabelle Shuping
 
 This program is free software: you can redistribute it and/or modify
@@ -16,8 +16,8 @@
 along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
-from modules.types import common
-from modules.types.Option import Option, Nothing, Some
+from exseos.types import common
+from exseos.types.Option import Option, Nothing, Some
 
 from abc import ABC, abstractmethod
 import logging
@@ -29,15 +29,17 @@
 
 
 class Variable[A](ABC):
-	"""Stores a quantity whose value can vary from workflow to workflow,
+	"""
+	Stores a quantity whose value can vary from workflow to workflow,
 	controlled either statically (manually set in configuration) or
 	dynamically (controlled by an optimizer)
 	"""
 
 	@property
 	@abstractmethod
 	def is_bound(self) -> bool:
-		"""`True` iff this variable has been bound to a value.
+		"""
+		`True` iff this variable has been bound to a value.
 
 		Note that `Variable.val` will only return a value if the variable is
 		bound; otherwise, a `TypeError` will be raised.
@@ -59,7 +61,8 @@ def desc(self) -> Option[str]:
 	@property
 	@abstractmethod
 	def val(self) -> A:
-		"""The bound value of this Variable. Only exists if `is_bound` is True;
+		"""
+		The bound value of this Variable. Only exists if `is_bound` is True;
 		otherwise, a `TypeError` will be raised.
 		"""
 		...  # pragma: no cover
@@ -73,7 +76,8 @@ def var_type(self) -> Option[type]:
 	@property
 	@abstractmethod
 	def var_type_inferred(self) -> bool:
-		"""True if `var_type` was automatically inferred (and thus potentially
+		"""
+		True if `var_type` was automatically inferred (and thus potentially
 		inaccurate); False if it was explicitly provided.
 		"""
 		...  # pragma: no cover

modules/report/ReportProvider.py → exseos/report/ReportProvider.py

@@ -1,5 +1,5 @@
 """
-Chicory ML Workflow Manager
+ExSeOS-H Hardware ML Workflow Manager
 Copyright (C) 2024  Alexis Maya-Isabelle Shuping
 
 This program is free software: you can redistribute it and/or modify

modules/types/ComparableError.py → exseos/types/ComparableError.py

@@ -1,5 +1,5 @@
 """
-Chicory ML Workflow Manager
+ExSeOS-H Hardware ML Workflow Manager
 Copyright (C) 2024  Alexis Maya-Isabelle Shuping
 
 This program is free software: you can redistribute it and/or modify

modules/types/Either.py → exseos/types/Either.py

@@ -1,5 +1,5 @@
 """
-Chicory ML Workflow Manager
+ExSeOS-H Hardware ML Workflow Manager
 Copyright (C) 2024  Alexis Maya-Isabelle Shuping
 
 This program is free software: you can redistribute it and/or modify
@@ -16,7 +16,7 @@
 along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
-from modules.types.ComparableError import ComparableError
+from exseos.types.ComparableError import ComparableError
 
 from typing import TypeVar, Callable
 from abc import ABC, abstractmethod
@@ -43,40 +43,44 @@ def is_right(self) -> bool:
 	@property
 	@abstractmethod
 	def val(self) -> B:
-		"""Return the inner value of a Right.
+		"""
+		Return the inner value of a Right.
 
-		@warning Raises a TypeError if called on a Left.
+		:raises TypeError: If called on a Left.
 		"""
 		...  # pragma: no cover
 
 	@property
 	@abstractmethod
 	def lval(self) -> B:
-		"""Return the inner value of a Left.
+		"""
+		Return the inner value of a Left.
 
-		@warning Raises a TypeError if called on a Right.
+		:raises TypeError: if called on a Right.
 		"""
 		...  # pragma: no cover
 
 	@abstractmethod
 	def map(self, f: Callable[[B], C]) -> "Either[A, C]":
-		"""If this Either is a Right, call `f` on its rval and return a Right()
-		of the result.
+		"""
+		If this Either is a Right, call `f` on its rval and return a Right() of
+		the result.
 
-		If it is a Left, do not call `f` and just return a Left() of the
-		lval.
+		If it is a Left, do not call `f` and just return a Left() of the lval.
 		"""
 		...  # pragma: no cover
 
 	@abstractmethod
 	def flat_map(self, f: Callable[[B], "Either[A, C]"]) -> "Either[A, C]":
-		"""Similar to Map, except that `f` should convert `B`'s directly into
-		an `Either`.
+		"""
+		Similar to Map, except that `f` should convert `B`'s directly into an
+		`Either`.
 		"""
 		...  # pragma: no cover
 
 	def __eq__(self, other) -> bool:
-		"""Returns True iff both Eithers being compared are the same type (i.e.
+		"""
+		Returns True iff both Eithers being compared are the same type (i.e.
 		both Left or both Right) AND the relevant inner values are the same.
 		"""
 		if not issubclass(type(other), Either):

modules/types/Option.py → exseos/types/Option.py

@@ -1,5 +1,5 @@
 """
-Chicory ML Workflow Manager
+ExSeOS-H Hardware ML Workflow Manager
 Copyright (C) 2024  Alexis Maya-Isabelle Shuping
 
 This program is free software: you can redistribute it and/or modify
@@ -16,7 +16,7 @@
 along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
-from modules.types.ComparableError import ComparableError
+from exseos.types.ComparableError import ComparableError
 
 from typing import TypeVar, Callable
 from abc import ABC, abstractmethod
@@ -41,16 +41,18 @@ def has_val(self) -> bool:
 	@property
 	@abstractmethod
 	def val(self) -> A:
-		"""Return the inner value of a `Some[A]`.
+		"""
+		Return the inner value of a `Some[A]`.
 
-		@warning Raises a TypeError if called on `Nothing`.
+		:raises TypeError: if called on `Nothing`.
 		"""
 		...  # pragma: no cover
 
 	@abstractmethod
 	def map(self, f: Callable[[A], B]) -> "Option[B]":
-		"""If this is `Some[A]`, call `f` on its value and return a `Some[B]`
-		of the result.
+		"""
+		If this is `Some[A]`, call `f` on its value and return a `Some[B]` of
+		the result.
 
 		If it is `Nothing`, do not call `f` and just return `Nothing`.
 
@@ -61,24 +63,25 @@ def map(self, f: Callable[[A], B]) -> "Option[B]":
 
 	@abstractmethod
 	def flat_map(self, f: Callable[[A], "Option[B]"]) -> "Option[B]":
-		"""Similar to Map, except that `f` should convert `A`'s directly into
+		"""
+		Similar to Map, except that `f` should convert `A`'s directly into
 		`Option[B]`'s.
 
-		:param f: A function that takes an `A` and converts it to an
-		    `Option[B]`
+		:param f: A function that takes an `A` and converts it to an `Option[B]`
 		:returns: `f(a)` if this `Option` is `Some(a)`, else `Nothing()`
 		"""
 		...  # pragma: no cover
 
 	@staticmethod
 	def make_from(obj: any) -> "Option[A]":
-		"""Convenience method to ensure an object is an Option. If `obj` is
-		already an Option, it is returned as-is. If `obj` is None, it is
-		converted to `Nothing()`. Otherwise, it is converted to `Some(obj)`
+		"""
+		Convenience method to ensure an object is an Option. If `obj` is already
+		an Option, it is returned as-is. If `obj` is None, it is converted to
+		`Nothing()`. Otherwise, it is converted to `Some(obj)`
 
 		:param obj: The object to encapsulate
-		:returns: `obj` if `obj` is an Option; otherwise, `Some(obj)` if obj
-		    is not None; otherwise, `Nothing()`.
+		:returns: `obj` if `obj` is an Option; otherwise, `Some(obj)` if obj is
+		    not None; otherwise, `Nothing()`.
 		"""
 		...  # pragma: no cover
 

modules/types/Result.py → exseos/types/Result.py

@@ -1,5 +1,5 @@
 """
-Chicory ML Workflow Manager
+ExSeOS-H Hardware ML Workflow Manager
 Copyright (C) 2024  Alexis Maya-Isabelle Shuping
 
 This program is free software: you can redistribute it and/or modify
@@ -16,7 +16,7 @@
 along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
-from modules.types.ComparableError import ComparableError
+from exseos.types.ComparableError import ComparableError
 
 from typing import TypeVar, Callable, List
 from abc import ABC, abstractmethod
@@ -28,15 +28,16 @@
 
 
 class Result[A, B, C](ABC):
-	"""Represents the result of a computation.
+	"""
+	Represents the result of a computation.
 
 	Can either be `Okay[C]`, `Warning[B, C]`, or `Error[A, B]`.
 
 	`val` of type `C` represents the return type of the computation. It is
 	present in `Okay` and `Warning` types, but not `Error` types.
 
-	`warn` of type `B` represents non-fatal warnings. It is present in
-	`Warning` and `Error` types, but not `Okay` types.
+	`warn` of type `B` represents non-fatal warnings. It is present in `Warning`
+	and `Error` types, but not `Okay` types.
 
 	`err` of type `A` represents fatal errors. It is only present in `Error`
 	types.
@@ -63,42 +64,53 @@ def is_error(self) -> bool:
 	@property
 	@abstractmethod
 	def val(self) -> C:
-		"""Return the result of the computation.
+		"""
+		Return the result of the computation.
 
-		This is present for `Okay` and `Warning` types. It is NOT present
-		for `Error` types.
+		This is present for `Okay` and `Warning` types. It is NOT present for
+		`Error` types.
+		
+		:raises TypeError: if called on an `Error`
 		"""
 		...  # pragma: no cover
 
 	@property
 	@abstractmethod
 	def warnings(self) -> List[B]:
-		"""Return the list of warnings generated during the computation.
+		"""
+		Return the list of warnings generated during the computation.
 
-		This is present for `Warning` and `Error` types. It is NOT present
-		for `Okay` types.
+		This is present for `Warning` and `Error` types. It is NOT present for
+		`Okay` types.
+
+		:raises TypeError: if called on an `Okay`
 		"""
 		...  # pragma: no cover
 
 	@property
 	@abstractmethod
 	def errors(self) -> List[A]:
-		"""Return the list of fatal errors generated during the computation.
+		"""
+		Return the list of fatal errors generated during the computation.
 
 		This is only present for `Error` types.
+
+		:raises TypeError: if called on an `Okay` or `Warning`
 		"""
 		...  # pragma: no cover
 
 	@abstractmethod
 	def map(self, f: Callable[[C], D]) -> "Result[A, B, D]":
-		"""If this `Result` is `Okay` or `Warning`, call `f` on its value and
+		"""
+		If this `Result` is `Okay` or `Warning`, call `f` on its value and
 		return an `Okay` or `Warning` of the result.
 		"""
 		...  # pragma: no cover
 
 	@abstractmethod
 	def flat_map(self, f: Callable[[C], "Result[A, B, D]"]) -> "Result[A, B, D]":
-		"""If this `Result` is `Okay` or `Warning`, call `f` on its value and
+		"""
+		If this `Result` is `Okay` or `Warning`, call `f` on its value and
 		return the output, which must itself be a `Result`.
 		"""
 		...  # pragma: no cover
@@ -154,7 +166,8 @@ def __eq__(self, other):
 
 
 class Okay[C](Result):
-	"""Represents a computation that has succeeded without any errors or warnings.
+	"""
+	Represents a computation that has succeeded without any errors or warnings.
 
 	Has a `val`, but no `warnings` or `errors`
 	"""
@@ -197,7 +210,8 @@ def __str__(self) -> str:
 
 
 class Warning[B, C](Result):
-	"""Represents a computation that encountered non-fatal errors.
+	"""
+	Represents a computation that encountered non-fatal errors.
 
 	Has a `val` and `warnings`, but no `errors`
 	"""
@@ -247,7 +261,8 @@ def __str__(self) -> str:
 
 
 class Error[A, B](Result):
-	"""Represents a computation which failed with errors.
+	"""
+	Represents a computation which failed with errors.
 
 	Has `warnings` and `errors`, but no `val`.
 	"""