value-object-pattern 0.1.0__tar.gz

value_object_pattern-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+# linting files
+.coverage
+
+# cache files/folders
+**cache**
+
+# build and distribution files/folders
+**dist**
+**build**
+
+# environment folders
+**.venv**

value_object_pattern-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) (2024-2025) adriamontoto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

value_object_pattern-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: value-object-pattern
+Version: 0.1.0
+Summary: The Value Object Pattern is a Python package that streamlines the creation and management of value objects in your projects.
+Project-URL: Homepage, https://github.com/adriamontoto/value-object-pattern
+Project-URL: Repository, https://github.com/adriamontoto/value-object-pattern
+Project-URL: Issues, https://github.com/adriamontoto/value-object-pattern/issues
+Author: Adria Montoto
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: development,domain-driven-design,encapsulation,pattern,python,tools,utilities,validation,value-object
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: python-dateutil>=2.9.0
+Description-Content-Type: text/markdown
+
+<a name="readme-top"></a>
+
+# 📦 Value Object Pattern
+
+<p align="center">
+    <a href="https://github.com/adriamontoto/value-object-pattern/actions/workflows/ci.yaml?event=push&branch=master" target="_blank">
+        <img src="https://github.com/adriamontoto/value-object-pattern/actions/workflows/ci.yaml/badge.svg?event=push&branch=master" alt="CI Pipeline">
+    </a>
+        <a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/adriamontoto/value-object-pattern" target="_blank">
+        <img src="https://coverage-badge.samuelcolvin.workers.dev/adriamontoto/value-object-pattern.svg" alt="Coverage Pipeline">
+    </a>
+    <a href="https://pypi.org/project/value-object-pattern" target="_blank">
+        <img src="https://img.shields.io/pypi/v/value-object-pattern?color=%2334D058&label=pypi%20package" alt="Package Version">
+    </a>
+    <a href="https://pypi.org/project/value-object-pattern/" target="_blank">
+        <img src="https://img.shields.io/pypi/pyversions/value-object-pattern.svg?color=%2334D058" alt="Supported Python Versions">
+    </a>
+</p>
+
+The **Value Object Pattern** is a Python 🐍 package that streamlines the creation and management of value objects 📦 in your projects. Value objects are immutable, self-validating objects that represent descriptive aspects of the domain with no conceptual identity. This pattern is essential for maintaining clean 🧹, maintainable, and bug-resistant 🐛 codebases by encapsulating domain-specific logic and ensuring consistency across your application 📱.
+<br><br>
+
+## Table of Contents
+
+- [📥 Installation](#installation)
+- [🤝 Contributing](#contributing)
+- [🔑 License](#license)
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="installation"></a>
+
+## 📥 Installation
+
+You can install **Value Object Pattern** using `pip`:
+
+```bash
+pip install value-object-pattern
+```
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="contributing"></a>
+
+## 🤝 Contributing
+
+We love community help! Before you open an issue or pull request, please read:
+
+- [`🤝 How to Contribute`](https://github.com/adriamontoto/value-object-pattern/blob/master/.github/CONTRIBUTING.md)
+- [`🧭 Code of Conduct`](https://github.com/adriamontoto/value-object-pattern/blob/master/.github/CODE_OF_CONDUCT.md)
+- [`🔐 Security Policy`](https://github.com/adriamontoto/value-object-pattern/blob/master/.github/SECURITY.md)
+
+_Thank you for helping make **📦 Value Object Pattern** package awesome! 🌟_
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="license"></a>
+
+## 🔑 License
+
+This project is licensed under the terms of the [`MIT license`](https://github.com/adriamontoto/value-object-pattern/blob/master/LICENSE.md).
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p>

value_object_pattern-0.1.0/README.md

@@ -0,0 +1,71 @@
+<a name="readme-top"></a>
+
+# 📦 Value Object Pattern
+
+<p align="center">
+    <a href="https://github.com/adriamontoto/value-object-pattern/actions/workflows/ci.yaml?event=push&branch=master" target="_blank">
+        <img src="https://github.com/adriamontoto/value-object-pattern/actions/workflows/ci.yaml/badge.svg?event=push&branch=master" alt="CI Pipeline">
+    </a>
+        <a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/adriamontoto/value-object-pattern" target="_blank">
+        <img src="https://coverage-badge.samuelcolvin.workers.dev/adriamontoto/value-object-pattern.svg" alt="Coverage Pipeline">
+    </a>
+    <a href="https://pypi.org/project/value-object-pattern" target="_blank">
+        <img src="https://img.shields.io/pypi/v/value-object-pattern?color=%2334D058&label=pypi%20package" alt="Package Version">
+    </a>
+    <a href="https://pypi.org/project/value-object-pattern/" target="_blank">
+        <img src="https://img.shields.io/pypi/pyversions/value-object-pattern.svg?color=%2334D058" alt="Supported Python Versions">
+    </a>
+</p>
+
+The **Value Object Pattern** is a Python 🐍 package that streamlines the creation and management of value objects 📦 in your projects. Value objects are immutable, self-validating objects that represent descriptive aspects of the domain with no conceptual identity. This pattern is essential for maintaining clean 🧹, maintainable, and bug-resistant 🐛 codebases by encapsulating domain-specific logic and ensuring consistency across your application 📱.
+<br><br>
+
+## Table of Contents
+
+- [📥 Installation](#installation)
+- [🤝 Contributing](#contributing)
+- [🔑 License](#license)
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="installation"></a>
+
+## 📥 Installation
+
+You can install **Value Object Pattern** using `pip`:
+
+```bash
+pip install value-object-pattern
+```
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="contributing"></a>
+
+## 🤝 Contributing
+
+We love community help! Before you open an issue or pull request, please read:
+
+- [`🤝 How to Contribute`](https://github.com/adriamontoto/value-object-pattern/blob/master/.github/CONTRIBUTING.md)
+- [`🧭 Code of Conduct`](https://github.com/adriamontoto/value-object-pattern/blob/master/.github/CODE_OF_CONDUCT.md)
+- [`🔐 Security Policy`](https://github.com/adriamontoto/value-object-pattern/blob/master/.github/SECURITY.md)
+
+_Thank you for helping make **📦 Value Object Pattern** package awesome! 🌟_
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="license"></a>
+
+## 🔑 License
+
+This project is licensed under the terms of the [`MIT license`](https://github.com/adriamontoto/value-object-pattern/blob/master/LICENSE.md).
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p>

value_object_pattern-0.1.0/pyproject.toml

@@ -0,0 +1,217 @@
+[build-system]
+requires = ['hatchling']
+build-backend = 'hatchling.build'
+
+
+[tool.hatch.version]
+path = 'value_object_pattern/__init__.py'
+
+[tool.hatch.build.targets.sdist]
+include = ['value_object_pattern/']
+
+
+[project]
+name = 'value-object-pattern'
+description = 'The Value Object Pattern is a Python package that streamlines the creation and management of value objects in your projects.'
+readme = './README.md'
+authors = [{ name = 'Adria Montoto' }]
+license = 'MIT'
+classifiers = [
+    'License :: OSI Approved :: MIT License',
+    'Intended Audience :: Developers',
+    'Operating System :: OS Independent',
+    'Typing :: Typed',
+    'Programming Language :: Python',
+    'Programming Language :: Python :: 3',
+    'Programming Language :: Python :: 3.11',
+    'Programming Language :: Python :: 3.12',
+    'Programming Language :: Python :: 3.13',
+]
+keywords = [
+    'python',
+    'development',
+    'tools',
+    'utilities',
+    'value-object',
+    'encapsulation',
+    'pattern',
+    'validation',
+    'domain-driven-design',
+]
+requires-python = '>=3.11'
+dependencies = ['python-dateutil>=2.9.0']
+dynamic = ['version']
+
+[project.urls]
+Homepage = 'https://github.com/adriamontoto/value-object-pattern'
+Repository = 'https://github.com/adriamontoto/value-object-pattern'
+Issues = 'https://github.com/adriamontoto/value-object-pattern/issues'
+
+
+[dependency-groups]
+audit = ['pip-audit>=2.9.0']
+coverage = ['coverage[toml]>=7.0.0', 'smokeshow>=0.5.0']
+develop = ['pre-commit>=3.0.0']
+format = ['ruff>=0.11.10']
+lint = [
+    'ruff>=0.11.10',
+    'mypy[reports]>=1.0.0',
+    { include-group = 'test' },
+    { include-group = 'types' },
+]
+release = ['build>=1.2.2', 'python-semantic-release>=10.0.2']
+test = [
+    'pytest>=8.0.0',
+    'pytest-randomly>=3.0.0',
+    'object-mother-pattern>=1.0.0',
+    { include-group = 'coverage' },
+]
+types = ['types-python-dateutil>=2.9.0.20241206 ']
+all = [
+    { include-group = 'audit' },
+    { include-group = 'coverage' },
+    { include-group = 'develop' },
+    { include-group = 'format' },
+    { include-group = 'lint' },
+    { include-group = 'release' },
+    { include-group = 'test' },
+    { include-group = 'types' },
+]
+
+
+[tool.pytest.ini_options]
+pythonpath = '.'
+addopts = [
+    '--strict-config',  # fail if an unregistered option is used
+    '--strict-markers', # fail if an unregistered marker is used
+    '--color=yes',      # color the output
+]
+markers = ['unit_testing: Check a unique functionality']
+xfail_strict = true
+
+
+[tool.coverage.run]
+source = ['value_object_pattern']
+parallel = true
+branch = true
+relative_files = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+precision = 2
+exclude_lines = [
+    'pragma: no cover',
+    'raise NotImplementedError',
+    'if TYPE_CHECKING:',
+    'if typing.TYPE_CHECKING:',
+    '@overload',
+    '@typing.overload',
+    'typing.assert_never',
+    'assert_never',
+]
+
+[tool.coverage.paths]
+source = ['value_object_pattern']
+
+
+[tool.ruff]
+indent-width = 4
+line-length = 120
+target-version = 'py313'
+output-format = 'grouped'
+
+[tool.ruff.format]
+docstring-code-format = true
+docstring-code-line-length = 120
+indent-style = 'space'
+quote-style = 'single'
+skip-magic-trailing-comma = false
+
+[tool.ruff.lint]
+select = [
+    'F',    # pyflakes
+    'S',    # flake8-bandit
+    'B',    # flake8-bugbear
+    'DTZ',  # flake8-datetimez
+    'C4',   # flake8-comprehensions
+    'SIM',  # flake8-simplify
+    'I',    # isort
+    'C90',  # mccabe
+    'N',    # pep8-naming
+    'PERF', # perflint
+    'E',    # pycodestyle
+    'W',    # pycodestyle
+    'D',    # pydocstyle
+    'UP',   # pyupgrade
+    'RUF',  # ruff
+]
+ignore = [
+    'UP035',  # Checks for uses of deprecated imports based on the minimum supported Python version.
+    'UP036',  # Checks for conditional blocks gated on sys.version_info comparisons that are outdated for the minimum supported Python version.
+    'E111',   # Checks for indentation with a non-multiple of 4 spaces.
+    'E114',   # Checks for indentation of comments with a non-multiple of 4 spaces.
+    'E117',   # Checks for over-indented code.
+    'W191',   # Checks for indentation that uses tabs.
+    'D200',   # Checks for single-line docstrings that are broken across multiple lines.
+    'D205',   # 1 blank line required between summary line and description.
+    'D206',   # Checks for docstrings that are indented with tabs.
+    'D212',   # Checks for docstring summary lines that are not positioned on the first physical line of the docstring.
+    'D401',   # First line of docstring should be in imperative mood.
+    'D300',   # Checks for docstrings that use '''triple single quotes''' instead of 'triple double quotes'.
+    'RUF100', # Checks for unused noqa directives.
+]
+
+[tool.ruff.lint.per-file-ignores]
+'__init__.py' = [
+    'F401', # Checks for unused imports.
+    'D104', # Checks for undocumented public package definitions.
+]
+'**test**.py' = [
+    'S101', # Use of `assert` detected.
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.lint.pydocstyle]
+convention = 'pep257'
+
+[tool.ruff.lint.isort]
+case-sensitive = true
+known-first-party = ['value_object_pattern']
+combine-as-imports = true
+
+
+[tool.mypy]
+strict = true
+warn_unreachable = true
+enable_error_code = [
+    'redundant-expr',
+    'possibly-undefined',
+    'truthy-bool',
+    'explicit-override',
+]
+
+
+[tool.semantic_release]
+allow_zero_version = true
+commit_message = 'bump: new version {version} released'
+commit_parser = 'conventional'
+major_on_zero = true
+no_git_verify = false
+tag_format = 'v{version}'
+version_variables = ['value_object_pattern/__init__.py:__version__']
+
+[tool.semantic_release.commit_parser_options]
+minor_tags = ['feat']
+patch_tags = ['fix', 'perf', 'build']
+allowed_tags = ['feat', 'fix', 'perf', 'build']
+default_bump_level = 0
+parse_squash_commits = false
+ignore_merge_commits = true
+
+[tool.semantic_release.changelog]
+template_dir = 'docs/changelog_template'
+mode = 'update'
+exclude_commit_patterns = ['''Merged? .*''']

value_object_pattern-0.1.0/value_object_pattern/__init__.py

@@ -0,0 +1,10 @@
+__version__ = '0.1.0'
+
+from .decorators import process, validation
+from .models import ValueObject
+
+__all__ = (
+    'ValueObject',
+    'process',
+    'validation',
+)

value_object_pattern-0.1.0/value_object_pattern/decorators/__init__.py

@@ -0,0 +1,7 @@
+from .value_object_process import process
+from .value_object_validation import validation
+
+__all__ = (
+    'process',
+    'validation',
+)

value_object_pattern-0.1.0/value_object_pattern/decorators/value_object_process.py

@@ -0,0 +1,83 @@
+"""
+Process decorator for value object pattern.
+"""
+
+from functools import wraps
+from typing import Any, Callable, TypeVar
+
+T = TypeVar('T')
+
+
+def process(order: int | None = None) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Decorator for process the value after the value is validated.
+
+    Args:
+        order (int | None, optional): The order of the process that will be executed, if None the functions will be
+        executed alphabetically. Defaults to None.
+
+    Raises:
+        TypeError: If the order is not an integer.
+        ValueError: If the order is not equal or greater than 0.
+
+    Returns:
+        Callable[[Callable[..., T]], Callable[..., T]]: Wrapper function for the process.
+
+    Example:
+    ```python
+    from value_object_pattern import ValueObject, process
+
+
+    class UpperStringValueObject(ValueObject[str]):
+        @process()
+        def ensure_value_is_upper(self, value: str) -> str:
+            return value.upper()
+
+
+    string = UpperStringValueObject(value='hello world')
+    print(string)
+    # >>> HELLO WORLD
+    ```
+    """
+
+    def decorator(function: Callable[..., T]) -> Callable[..., T]:
+        """
+        Decorator for process the value after the value is validated.
+
+        Args:
+            function (Callable[..., T]): Function to be execution after the value object is validated.
+
+        Raises:
+            TypeError: If the order is not an integer.
+            ValueError: If the order is not equal or greater than 0.
+
+        Returns:
+            Callable[..., T]: Wrapper function for the process.
+        """
+        if order is not None:
+            if type(order) is not int:
+                raise TypeError(f'Process order <<<{order}>>> must be an integer. Got <<<{type(order).__name__}>>> type.')  # noqa: E501  # fmt: skip
+
+            if order < 0:
+                raise ValueError(f'Process order <<<{order}>>> must be equal or greater than 0.')
+
+        function._is_process = True  # type: ignore[attr-defined]
+        function._order = function.__name__ if order is None else str(order)  # type: ignore[attr-defined]
+
+        @wraps(wrapped=function)
+        def wrapper(*args: tuple[Any, ...], **kwargs: dict[str, Any]) -> T:
+            """
+            Wrapper for process.
+
+            Args:
+                *args (tuple[Any, ...]): The arguments for the function.
+                **kwargs (dict[str, Any]): The keyword arguments for the function.
+
+            Returns:
+                T: The return value of the function.
+            """
+            return function(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

value_object_pattern-0.1.0/value_object_pattern/decorators/value_object_validation.py

@@ -0,0 +1,78 @@
+"""
+Validation decorator for value object pattern.
+"""
+
+from functools import wraps
+from typing import Any, Callable
+
+
+def validation(order: int | None = None) -> Callable[[Callable[..., None]], Callable[..., None]]:
+    """
+    Decorator for validation the value before the value is created.
+
+    Args:
+        order (int | None, optional): The order of the validation that will be executed, if None the functions will be
+        executed alphabetically. Defaults to None.
+
+    Raises:
+        TypeError: If the order is not an integer.
+        ValueError: If the order is not equal or greater than 0.
+
+    Returns:
+        Callable[[Callable[..., None]], Callable[..., None]]: Wrapper function for the validation.
+
+    Example:
+    ```python
+    from value_object_pattern import ValueObject, validation
+
+
+    class IntegerValueObject(ValueObject[int]):
+        @validation()
+        def ensure_value_is_integer(self, value: int) -> None:
+            if type(value) is not int:
+                raise TypeError(f'IntegerValueObject value <<<{value}>>> must be an integer. Got <<<{type(value).__name__}>>> type.')
+
+
+    integer = IntegerValueObject(value='invalid')
+    # >>> TypeError: IntegerValueObject value <<<invalid>>> must be an integer. Got <<<str>>> type.
+    ```
+    """  # noqa: E501 # fmt: skip
+
+    def decorator(function: Callable[..., None]) -> Callable[..., None]:
+        """
+        Decorator for validation the value before the value is created.
+
+        Args:
+            function (Callable[..., None]): Function to be execution before the value object is created.
+
+        Raises:
+            TypeError: If the order is not an integer.
+            ValueError: If the order is not equal or greater than 0.
+
+        Returns:
+            Callable[..., None]: Wrapper function for the validation.
+        """
+        if order is not None:
+            if type(order) is not int:
+                raise TypeError(f'Validation order <<<{order}>>> must be an integer. Got <<<{type(order).__name__}>>> type.')  # noqa: E501  # fmt: skip
+
+            if order < 0:
+                raise ValueError(f'Validation order <<<{order}>>> must be equal or greater than 0.')
+
+        function._is_validation = True  # type: ignore[attr-defined]
+        function._order = function.__name__ if order is None else str(order)  # type: ignore[attr-defined]
+
+        @wraps(wrapped=function)
+        def wrapper(*args: tuple[Any, ...], **kwargs: dict[str, Any]) -> None:
+            """
+            Wrapper for validation.
+
+            Args:
+                *args (tuple[Any, ...]): The arguments for the function.
+                **kwargs (dict[str, Any]): The keyword arguments for the function.
+            """
+            function(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

value_object_pattern-0.1.0/value_object_pattern/models/__init__.py

@@ -0,0 +1,3 @@
+from .value_object import ValueObject
+
+__all__ = ('ValueObject',)