dataclassbase 0.1.0__tar.gz

dataclassbase-0.1.0/.github/workflows/check_and_deploy.yml

@@ -0,0 +1,131 @@
+name: Python Lint, Format, Test, Deploy
+
+on:
+  push:
+    branches:
+      - "**"
+  pull_request:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    name: Lint, Check formatting, Static Type-Check, Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff mypy pytest pytest-cov pytest-markdown-summary
+          pip install -e .
+
+      - name: Install pyproject.toml
+        run: pip install .
+
+      - name: Ruff lint
+        run: ruff check --output-format=github --target-version=py314
+
+      - name: Ruff format
+        run: ruff format --diff --target-version=py314
+
+      - name: MyPy
+        run: mypy dataclassbase
+
+      - name: Run tests
+        run: |
+          mkdir summary
+          pytest --cov=dataclassbase --cov-report=markdown-append:summary/coverage.md --markdown-summary-file=summary/summary.md
+          echo -e "# Summary\n" >> $GITHUB_STEP_SUMMARY
+          cat summary/summary.md >> $GITHUB_STEP_SUMMARY
+          echo -e "\n# Coverage\n" >> $GITHUB_STEP_SUMMARY
+          cat summary/coverage.md >> $GITHUB_STEP_SUMMARY
+
+  build_for_testpypi:
+    name: Build project for TestPyPI
+    runs-on: ubuntu-latest
+    env:
+      SETUPTOOLS_SCM_OVERRIDES_FOR_DATACLASSBASE: '{local_scheme = "no-local-version-strict"}'
+
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+            fetch-depth: 0
+
+      - uses: hynek/build-and-inspect-python-package@v2
+
+  publish-to-test-pypi:
+    name: Publish to TestPyPI
+    runs-on: ubuntu-latest
+    needs: [build_for_testpypi, test]
+
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')
+
+    environment:
+      name: testpypi
+
+      url: https://test.pypi.org/p/dataclassbase
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v6
+        with:
+          name: Packages
+          path: dist
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  # we may build and publish to PyPI
+  build_for_pypi:
+    name: Build project for PyPI
+    runs-on: ubuntu-latest
+
+    if: github.event_name == 'release'
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+            fetch-depth: 0
+
+      - uses: hynek/build-and-inspect-python-package@v2
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [build_for_pypi, test]
+
+    if: github.event_name == 'release'
+
+    environment:
+        name: pypi
+
+        url: https://pypi.org/p/dataclassbase
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v6
+        with:
+          name: Packages
+          path: dist
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

dataclassbase-0.1.0/.gitignore

@@ -0,0 +1,311 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/build/doctrees
+docs/source/_autogen
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+
+# https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+# Covers JetBrains IDEs: IntelliJ, GoLand, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/artifacts
+# .idea/compiler.xml
+# .idea/jarRepositories.xml
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+# *.iml
+# *.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+# see https://community.sonarsource.com/t/is-the-file-idea-idea-idea-sonarlint-xml-intended-to-be-under-source-control/121119
+.idea/sonarlint.xml
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based HTTP Client
+.idea/httpRequests
+http-client.private.env.json
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+# Apifox Helper cache
+.idea/.cache/.Apifox_Helper
+.idea/ApifoxUploaderProjectSetting.xml
+
+# Github Copilot persisted session migrations, see: https://github.com/microsoft/copilot-intellij-feedback/issues/712#issuecomment-3322062215
+.idea/**/copilot.data.migration.*.xml
+
+.idea

dataclassbase-0.1.0/.readthedocs.yaml

@@ -0,0 +1,21 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3"
+
+  jobs:
+    pre_build:
+      - sphinx-apidoc -o docs/source/_autogen python_ci_base
+
+sphinx:
+  configuration: docs/source/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

dataclassbase-0.1.0/LICENSE

@@ -0,0 +1,7 @@
+(c) Copyright 2026 Josef Mayr
+
+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.

dataclassbase-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: dataclassbase
+Version: 0.1.0
+Summary: Implement your own type of dataclass without the usual boilerplate code.
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: docs
+Requires-Dist: pydata_sphinx_theme; extra == "docs"
+Requires-Dist: setuptools; extra == "docs"
+Requires-Dist: setuptools_scm; extra == "docs"
+Dynamic: license-file
+
+# dataclassbase: Implement custom dataclasses
+
+## What it is and how to get it
+
+**dataclassbase** is a small toolkit for providing your own dataclasses. For dataclasses, attributes are declared via 
+annotations, and constructors are created automatically making development fast.
+
+However, often data in dataclasses shares common properties (e.g., data shape, etc.) or we might want to have more 
+control over the fields in dataclasses. This is where **dataclassbase** comes to help: You can define your own 
+dataclass-like behavior using `typing.dataclass_transform` or metaclasses, and control the behavior of your dataclass in
+a fine-grained manner.
+
+You can install it into your environment from PyPI via
+
+```shell
+pip install dataclassbase
+```
+
+
+## General note
+
+While the project is generally usable, it is not yet production-ready. It is, however, being actively developed since I 
+plan to use it as a base for further work.
+
+## License
+
+[MIT](./LICENSE)
+
+## The Basics
+
+The `dataclasses` module provides very basic dataclasses with little customization. The objective of this package is to
+overcome this limitation by providing customizable dataclasses.
+
+A possible definition for the built-in dataclasses is
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class SomeClass:
+    some_field: str
+    some_defaulting_field: int = 1
+```
+
+In this framework, a similar approach is possible:
+
+```python
+from dataclassbase import dataclass
+
+@dataclass
+class SomeClass:
+    some_field: str
+    some_defaulting_field: int = 1
+```
+
+The most obvious difference above is that we import from `dataclassbase` rather than `dataclasses`. However, looking at
+the signature of `dataclassbase.dataclass`, we note that there are two notable parameters: `field_provider` and 
+`object_handler`. `field_provider` allows customization of the field generation and processing (if the user provides a
+`dataclassbase.Field` as a default value), `object_handler` implements the logic for the initialization (`__init__`) and
+attribute assignment (`__setattr__`) of objects of the generated dataclass. We therefore can hook into or override the
+behavior of the dataclass.
+
+If you omit the `field_provider` or `object_handler`, the respective default implementations provided in the 
+`FieldProvider` and `ObjectHandler` classes, which reproduce the default dataclass behavior, are used instead.
+If you provide a callable matching the signature of `dataclassbase.Field` to `field_provider`, a `FieldProvider` is
+generated. Therefore, you can directly specify the type of field to use, as long as it matches the respective signature.
+You can also replace the `default`-value if it indicates a value you want to process.
+
+Note that while it suffices to call `dataclassbase.dataclass` on a class to initialize dataclass-like behavior, it does
+not truly behave like a dataclass to static type checkers since it lacks the `typing.dataclass_transform` decorator.
+My reason for that choice is that I would have to fix the `field_specifiers` parameter.
+(Instances of the types provided in `field_specifiers` are allowed as default values for fields since they are
+assumed to be fields or to be converted into some. We do that conversion in the provided `field_provider`.)
+In doing so, I would constrain proper static type checking on the fields. Therefore, I would rather let you indicate the
+types yourself.
+To achieve true dataclass-like behavior on a type checker, you can call `typing.dataclass_transform` yourself or rely on
+a metaclass derived from `DataclassMetaBase[TField]`:
+
+Rather than using `dataclassbase.dataclass` as above, you can define your own dataclass by deriving a metaclass from
+class `DataclassMetaBase[TField]` and attaching a `typing.dataclass_transform` to it. `DataclassMetaBase` invokes 
+`make_dataclass` when creating the new type (`dataclass` is the decorator-variant of `make_dataclass`). It provides
+the methods `_field_provider` and `_object_handler` which act as factories for the field provider and object handler for
+the types using the metaclass.
+
+```python
+from dataclassbase import DataclassMetaBase, Field, FieldProvider
+from typing import dataclass_transform
+
+
+class CustomField(Field):
+    # you can override the methods provided by `Field` to control the behavior of the field in derived classes,
+    # superclasses, to check the assignments, etc. You can also change the behavior of `__init__` as long as its 
+    # signature matches the one from the base
+    pass
+
+
+@dataclass_transform
+class CustomDataclassMeta(DataclassMetaBase[Field]):
+    @classmethod
+    def _field_provider(cls) -> FieldProvider[Field]:
+        # we want it to return our custom field. The factory works since the signature of `CustomField.__init__` matches
+        # the one of `Field.__init__`
+        return FieldProvider(CustomField)
+    
+class VariantA(metaclass=CustomDataclassMeta):
+    field: int
+    defaulting: int = 1
+```
+
+`dataclassbase.Field`s themselves can check whether the value assigned to them is valid. Furthermore, they can check 
+whether fields in derived classes are valid and, in the opposite direction, whether they are valid overrides of fields
+of superclasses. As an example, you can look at the provided `dataclassbase.TypeConstrainedField` which provides
+simple type checking via `isinstance`.
+
+The default implementation is `DataclassMeta` which just uses the default values and allows any 
+`dataclasses.Field` as a default value for its fields. While it behaves in the same way as the built-in 
+`dataclasses`-dataclasses, it does however not give us any benefits over it.
+
+```python
+from dataclassbase import DataclassMeta
+
+class VariantB(metaclass=DataclassMeta):
+    field: int
+    defaulting: int = 1    
+```
+
+## Fine-tuning the behavior of the dataclasses
+
+`dataclasses.dataclass` comes with quite a lot of nice additions: We can freeze the dataclass, equality and unequality
+operators get generated, a hash function may be provided, and so forth. This behavior can be imitated using the classes
+derived from the `BehaviorModifier` type. For now, these are
+
+* `Frozen`: Dataclasses cannot be assigned new values and cannot be reinitialized
+* `Representable`: Adds a string representation via `__repr__` and `__str__`
+* `Equatable`: Adds overloads for `__eq__` and `__ne__`, and, optionally, for `__hash__`
+* `PositionalOnly`: The initializer only allows positional arguments
+* `KeywordOnly`: The initializer only allows keyword arguments
+
+Add these as `modifiers` when calling `dataclass` or `make_dataclass` or return them as `_modifiers` in metaclasses 
+derived from `DataclassMetaBase`.
+
+Note that some of the behaviors are "unsafe", and it is up to you to decide whether your use-case is safe. For 
+example, hash codes typically change once fields of the dataclass change. Using such a class as a key is unsafe. You 
+thus will typically combine `Frozen` and `Equatable`. Note that `Frozen` does not affect nested dataclasses: If these
+are not frozen, the dataclass itself may still be mutable. Another unsafe example is the combination of `PositionalOnly`
+and `KeywordOnly` which does not make any sense, but is not caught for now.
+
+I may add such safeguards later, but for now it is obvious that such combinations do not make any sense.
+
+# When to use dataclassbase and not ...?
+
+## Pydantic
+
+Pydantic's objective is to provide fast data validation and serialization [[1]](https://pydantic.dev/docs/validation/latest/get-started/).
+dataclassbase aims to be much more abstract since it is not constrained to a single use-case such as data validation, 
+and thus does (hopefully) not give too strong restrictions on what you can/cannot do.