validating 0.0.0__tar.gz → 0.0.1__tar.gz

validating-0.0.1/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: validating
+Version: 0.0.1
+Summary: Provides a lightweight `attr()` descriptor factory that adds runtime validation to dataclass fields.
+Project-URL: Documentation, https://github.com/Chitaoji/validating/blob/main/README.md
+Project-URL: Repository, https://github.com/Chitaoji/validating/
+Author-email: Chitaoji <2360742040@qq.com>
+Maintainer-email: Chitaoji <2360742040@qq.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: config
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# validating
+
+`validating` is a lightweight runtime validation library focused on making
+`dataclass` fields and function arguments safer and easier to validate.
+
+It exposes three main entry points:
+
+- `attr(...)`: declare validated fields (type checks, bounds, allow/deny lists, custom validators)
+- `@dataclass(...)`: a compatible enhancement of `dataclasses.dataclass` with automatic validation integration
+- `@validate`: a decorator that validates function arguments using type annotations
+
+## Installation
+
+```bash
+pip install validating
+```
+
+## Quick Start
+
+```python
+from validating import attr, dataclass
+
+@dataclass
+class UserConfig:
+    age: int = attr(lb=0)
+    role: str = attr(allowlist=["admin", "user"])
+
+cfg = UserConfig(age=18, role="admin")
+cfg.age = 20          # ✅
+cfg.role = "user"    # ✅
+# cfg.age = -1        # ❌ ValueError
+# cfg.role = "guest" # ❌ ValueError
+```
+
+## Core API
+
+### `attr(...)`
+
+Declares a descriptor-backed field that validates values on initialization and assignment.
+
+Common parameters:
+
+- `default`: default value
+- `default_factory`: lazy default factory (mutually exclusive with `default`)
+- `allowlist`: whitelist of allowed values
+- `denylist`: blacklist of forbidden values
+- `lb` / `ub`: inclusive lower / upper bounds
+- `slb` / `sub`: exclusive lower / upper bounds
+- `validator`: custom validator function with signature `Callable[[Any], bool]`
+- `init` / `repr` / `hash` / `compare` / `kw_only`: forwarded dataclass field behavior controls
+
+Error semantics:
+
+- Misconfiguration at class-definition time (for example, default type mismatch) raises `ValidatorError`
+- Invalid runtime values raise `TypeError` or `ValueError`
+
+---
+
+### `@dataclass(...)`
+
+`validating.dataclass` is a compatible enhanced wrapper around `dataclasses.dataclass`.
+
+Enhancements:
+
+1. **Automatic default promotion**: `x: int = 1` is promoted to `attr(default=1)`
+2. **Method argument validation**: when `validate_methods=True` (by default `False`), all public methods are wrapped with `validate` (including `@staticmethod` and `@classmethod`)
+
+```python
+from validating import dataclass
+
+@dataclass(validate_methods=True)
+class Service:
+    retries: int = 3
+
+    def run(self, timeout: int) -> int:
+        return timeout + self.retries
+
+svc = Service()
+svc.run(1)       # ✅
+# svc.run("1")   # ❌ TypeError
+```
+
+---
+
+### `@validate`
+
+Enables call-time argument validation based on type annotations.
+
+```python
+from typing import Literal
+from validating import validate
+
+@validate
+def configure(mode: Literal["dev", "prod"], workers: int):
+    return mode, workers
+
+configure("dev", 4)    # ✅
+# configure("test", 4)  # ❌ TypeError
+```
+
+`@validate` also handles `assert` statements in validated functions:
+
+- `assert <expr>, "custom message"` keeps the original `AssertionError` with your message.
+- `assert <expr>` (without message) is converted to a `ValueError` when `<expr>` is a direct assertion on function arguments, with a message like `expected <expr>, got <value> instead`.
+- Assertions that are not direct checks on function arguments are left as regular `AssertionError`.
+
+```python
+from validating import validate
+
+@validate
+def check_score(score: int) -> int:
+    assert score >= 60
+    return score
+
+check_score(80)   # ✅
+# check_score(59) # ❌ ValueError: expected score >= 60, got 59 instead
+```
+
+## More Examples
+
+### 1) `default_factory`
+
+```python
+from validating import attr, dataclass
+
+@dataclass
+class Cache:
+    items: list[int] = attr(default_factory=list)
+```
+
+### 2) Complex type hints
+
+```python
+from typing import Literal
+from validating import attr, dataclass
+
+@dataclass
+class AppConfig:
+    mode: Literal["dev", "prod"] = attr()
+    token: int | str = attr()
+    mapping: dict[str, int] = attr()
+```
+
+### 3) Custom validator
+
+```python
+from validating import attr, dataclass
+
+@dataclass
+class EvenNumber:
+    value: int = attr(validator=lambda x: x % 2 == 0)
+```
+
+## Notes
+
+- Dataclasses with `slots=True` are currently not supported.
+- This project focuses on runtime validation and does not replace static type checking.
+
+## See Also
+
+- GitHub: https://github.com/Chitaoji/validating/
+- PyPI: https://pypi.org/project/validating/
+
+## License
+This project falls under the BSD 3-Clause License.
+
+## History
+
+### v0.0.1
+
+- Initial release.

validating-0.0.1/README.md

@@ -0,0 +1,171 @@
+# validating
+
+`validating` is a lightweight runtime validation library focused on making
+`dataclass` fields and function arguments safer and easier to validate.
+
+It exposes three main entry points:
+
+- `attr(...)`: declare validated fields (type checks, bounds, allow/deny lists, custom validators)
+- `@dataclass(...)`: a compatible enhancement of `dataclasses.dataclass` with automatic validation integration
+- `@validate`: a decorator that validates function arguments using type annotations
+
+## Installation
+
+```bash
+pip install validating
+```
+
+## Quick Start
+
+```python
+from validating import attr, dataclass
+
+@dataclass
+class UserConfig:
+    age: int = attr(lb=0)
+    role: str = attr(allowlist=["admin", "user"])
+
+cfg = UserConfig(age=18, role="admin")
+cfg.age = 20          # ✅
+cfg.role = "user"    # ✅
+# cfg.age = -1        # ❌ ValueError
+# cfg.role = "guest" # ❌ ValueError
+```
+
+## Core API
+
+### `attr(...)`
+
+Declares a descriptor-backed field that validates values on initialization and assignment.
+
+Common parameters:
+
+- `default`: default value
+- `default_factory`: lazy default factory (mutually exclusive with `default`)
+- `allowlist`: whitelist of allowed values
+- `denylist`: blacklist of forbidden values
+- `lb` / `ub`: inclusive lower / upper bounds
+- `slb` / `sub`: exclusive lower / upper bounds
+- `validator`: custom validator function with signature `Callable[[Any], bool]`
+- `init` / `repr` / `hash` / `compare` / `kw_only`: forwarded dataclass field behavior controls
+
+Error semantics:
+
+- Misconfiguration at class-definition time (for example, default type mismatch) raises `ValidatorError`
+- Invalid runtime values raise `TypeError` or `ValueError`
+
+---
+
+### `@dataclass(...)`
+
+`validating.dataclass` is a compatible enhanced wrapper around `dataclasses.dataclass`.
+
+Enhancements:
+
+1. **Automatic default promotion**: `x: int = 1` is promoted to `attr(default=1)`
+2. **Method argument validation**: when `validate_methods=True` (by default `False`), all public methods are wrapped with `validate` (including `@staticmethod` and `@classmethod`)
+
+```python
+from validating import dataclass
+
+@dataclass(validate_methods=True)
+class Service:
+    retries: int = 3
+
+    def run(self, timeout: int) -> int:
+        return timeout + self.retries
+
+svc = Service()
+svc.run(1)       # ✅
+# svc.run("1")   # ❌ TypeError
+```
+
+---
+
+### `@validate`
+
+Enables call-time argument validation based on type annotations.
+
+```python
+from typing import Literal
+from validating import validate
+
+@validate
+def configure(mode: Literal["dev", "prod"], workers: int):
+    return mode, workers
+
+configure("dev", 4)    # ✅
+# configure("test", 4)  # ❌ TypeError
+```
+
+`@validate` also handles `assert` statements in validated functions:
+
+- `assert <expr>, "custom message"` keeps the original `AssertionError` with your message.
+- `assert <expr>` (without message) is converted to a `ValueError` when `<expr>` is a direct assertion on function arguments, with a message like `expected <expr>, got <value> instead`.
+- Assertions that are not direct checks on function arguments are left as regular `AssertionError`.
+
+```python
+from validating import validate
+
+@validate
+def check_score(score: int) -> int:
+    assert score >= 60
+    return score
+
+check_score(80)   # ✅
+# check_score(59) # ❌ ValueError: expected score >= 60, got 59 instead
+```
+
+## More Examples
+
+### 1) `default_factory`
+
+```python
+from validating import attr, dataclass
+
+@dataclass
+class Cache:
+    items: list[int] = attr(default_factory=list)
+```
+
+### 2) Complex type hints
+
+```python
+from typing import Literal
+from validating import attr, dataclass
+
+@dataclass
+class AppConfig:
+    mode: Literal["dev", "prod"] = attr()
+    token: int | str = attr()
+    mapping: dict[str, int] = attr()
+```
+
+### 3) Custom validator
+
+```python
+from validating import attr, dataclass
+
+@dataclass
+class EvenNumber:
+    value: int = attr(validator=lambda x: x % 2 == 0)
+```
+
+## Notes
+
+- Dataclasses with `slots=True` are currently not supported.
+- This project focuses on runtime validation and does not replace static type checking.
+
+## See Also
+
+- GitHub: https://github.com/Chitaoji/validating/
+- PyPI: https://pypi.org/project/validating/
+
+## License
+This project falls under the BSD 3-Clause License.
+
+## History
+
+### v0.0.1
+
+- Initial release.

{validating-0.0.0 → validating-0.0.1}/install.py

@@ -21,7 +21,6 @@ HOMEPAGE: Final[str] = project["urls"]["Repository"]
 REQUIRES: Final[list[str]] = project["dependencies"]
 SOURCE = "src"
 LICENSE = (here / project["license-files"][0]).read_text().partition("\n")[0]
-VERSION = project["version"]
 
 # Import the README and use it as the long-description.
 readme_path = here / project["readme"]
@@ -84,10 +83,6 @@ def _quote(readme: str) -> str:
         return f'"""{readme}"""'
 
 
-def _version(version: str = VERSION) -> str:
-    return f'"""Version file."""\n\n__version__ = "{version}"\n'
-
-
 class ReadmeFormatError(Exception):
     """Raised when the README has a wrong format."""
 
@@ -95,7 +90,6 @@ class ReadmeFormatError(Exception):
 if __name__ == "__main__":
     # Import the __init__.py and change the module docstring.
     init_path = here / SOURCE / NAME / "__init__.py"
-    version_path = here / SOURCE / NAME / "_version.py"
     module_file = init_path.read_text(encoding="utf-8")
     new_doc, long_description = _readme2doc(long_description)
     module_file = re.sub(
@@ -103,5 +97,4 @@ if __name__ == "__main__":
     )
     init_path.write_text(module_file, encoding="utf-8")
     readme_path.write_text(long_description.strip(), encoding="utf-8")
-    version_path.write_text(_version())
     os.system(f"cd {here} && python -m build")

{validating-0.0.0 → validating-0.0.1}/pyproject.toml

@@ -4,28 +4,25 @@ build-backend = "hatchling.build"
 
 [project]
 name = "validating"
-version = "0.0.0"
+version = "0.0.1"
 dependencies = []
-requires-python = ">=3.12"
+requires-python = ">=3.13"
 authors = [
   {name = "Chitaoji", email = "2360742040@qq.com"},
 ]
 maintainers = [
   {name = "Chitaoji", email = "2360742040@qq.com"}
 ]
-description = "For test"
+description = "Provides a lightweight `attr()` descriptor factory that adds runtime validation to dataclass fields."
 readme = "README.md"
 license = "BSD-3-Clause"
 license-files = ["LICENSE"]
 keywords = ["config"]
 classifiers = [
   "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.12"
+  "Programming Language :: Python :: 3.13"
 ]
 
 [project.urls]
 Documentation = "https://github.com/Chitaoji/validating/blob/main/README.md"
-Repository = "https://github.com/Chitaoji/validating/"
-
-[project.scripts]
-cfg = "template.__main__:run"
+Repository = "https://github.com/Chitaoji/validating/"

validating-0.0.1/src/validating/__init__.py

@@ -0,0 +1,179 @@
+"""
+# validating
+
+`validating` is a lightweight runtime validation library focused on making
+`dataclass` fields and function arguments safer and easier to validate.
+
+It exposes three main entry points:
+
+- `attr(...)`: declare validated fields (type checks, bounds, allow/deny lists, custom
+validators)
+- `@dataclass(...)`: a compatible enhancement of `dataclasses.dataclass` with automatic
+validation integration
+- `@validate`: a decorator that validates function arguments using type annotations
+
+## Quick Start
+
+```python
+from validating import attr, dataclass
+
+@dataclass
+class UserConfig:
+    age: int = attr(lb=0)
+    role: str = attr(allowlist=["admin", "user"])
+
+cfg = UserConfig(age=18, role="admin")
+cfg.age = 20          # ✅
+cfg.role = "user"    # ✅
+# cfg.age = -1        # ❌ ValueError
+# cfg.role = "guest" # ❌ ValueError
+```
+
+## Core API
+
+### `attr(...)`
+
+Declares a descriptor-backed field that validates values on initialization and
+assignment.
+
+Common parameters:
+
+- `default`: default value
+- `default_factory`: lazy default factory (mutually exclusive with `default`)
+- `allowlist`: whitelist of allowed values
+- `denylist`: blacklist of forbidden values
+- `lb` / `ub`: inclusive lower / upper bounds
+- `slb` / `sub`: exclusive lower / upper bounds
+- `validator`: custom validator function with signature `Callable[[Any], bool]`
+- `init` / `repr` / `hash` / `compare` / `kw_only`: forwarded dataclass field behavior
+controls
+
+Error semantics:
+
+- Misconfiguration at class-definition time (for example, default type mismatch) raises
+`ValidatorError`
+- Invalid runtime values raise `TypeError` or `ValueError`
+
+---
+
+### `@dataclass(...)`
+
+`validating.dataclass` is a compatible enhanced wrapper around `dataclasses.dataclass`.
+
+Enhancements:
+
+1. **Automatic default promotion**: `x: int = 1` is promoted to `attr(default=1)`
+2. **Method argument validation**: when `validate_methods=True` (by default `False`),
+all public methods are wrapped with `validate` (including `@staticmethod` and
+`@classmethod`)
+
+```python
+from validating import dataclass
+
+@dataclass(validate_methods=True)
+class Service:
+    retries: int = 3
+
+    def run(self, timeout: int) -> int:
+        return timeout + self.retries
+
+svc = Service()
+svc.run(1)       # ✅
+# svc.run("1")   # ❌ TypeError
+```
+
+---
+
+### `@validate`
+
+Enables call-time argument validation based on type annotations.
+
+```python
+from typing import Literal
+from validating import validate
+
+@validate
+def configure(mode: Literal["dev", "prod"], workers: int):
+    return mode, workers
+
+configure("dev", 4)    # ✅
+# configure("test", 4)  # ❌ TypeError
+```
+
+`@validate` also handles `assert` statements in validated functions:
+
+- `assert <expr>, "custom message"` keeps the original `AssertionError` with your
+message.
+- `assert <expr>` (without message) is converted to a `ValueError` when `<expr>` is a
+direct assertion on function arguments, with a message like `expected <expr>, got
+<value> instead`.
+- Assertions that are not direct checks on function arguments are left as regular
+`AssertionError`.
+
+```python
+from validating import validate
+
+@validate
+def check_score(score: int) -> int:
+    assert score >= 60
+    return score
+
+check_score(80)   # ✅
+# check_score(59) # ❌ ValueError: expected score >= 60, got 59 instead
+```
+
+## More Examples
+
+### 1) `default_factory`
+
+```python
+from validating import attr, dataclass
+
+@dataclass
+class Cache:
+    items: list[int] = attr(default_factory=list)
+```
+
+### 2) Complex type hints
+
+```python
+from typing import Literal
+from validating import attr, dataclass
+
+@dataclass
+class AppConfig:
+    mode: Literal["dev", "prod"] = attr()
+    token: int | str = attr()
+    mapping: dict[str, int] = attr()
+```
+
+### 3) Custom validator
+
+```python
+from validating import attr, dataclass
+
+@dataclass
+class EvenNumber:
+    value: int = attr(validator=lambda x: x % 2 == 0)
+```
+
+## Notes
+
+- Dataclasses with `slots=True` are currently not supported.
+- This project focuses on runtime validation and does not replace static type checking.
+
+## See Also
+
+- GitHub: https://github.com/Chitaoji/validating/
+- PyPI: https://pypi.org/project/validating/
+
+## License
+This project falls under the BSD 3-Clause License.
+
+"""
+
+from . import core
+from .core import *
+
+__all__: list[str] = []
+__all__.extend(core.__all__)

validating-0.0.1/src/validating/core.py

@@ -0,0 +1,13 @@
+"""
+Contains the core of validating: attr(), dataclass(), validate(), etc.
+
+NOTE: this module is private. All functions and objects are available in the main
+:mod:`validating` namespace - use that instead.
+
+"""
+
+from .datacls import dataclass
+from .valid_attr import ValidatorError, attr
+from .valid_func import validate
+
+__all__ = ["attr", "dataclass", "validate", "ValidatorError"]