worktoy 1.0.1.dev1__tar.gz → 1.1.0.dev1__tar.gz

{worktoy-1.0.1.dev1 → worktoy-1.1.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: worktoy
-Version: 1.0.1.dev1
+Version: 1.1.0.dev1
 Summary: Declarative structure for Python that enforces types at runtime and enables true function overloading
 Author-email: Asger Jon Vistisen <asgerjon2@gmail.com>
 License: Apache-2.0
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
@@ -32,12 +33,12 @@ Dynamic: license-file
 [![PyPI version](https://img.shields.io/pypi/v/worktoy)](https://pypi.org/project/worktoy/)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-# worktoy v1.0.1-dev1 (development build)
+# worktoy v1.1.0-dev1 (development build)
 
 **worktoy** provides utilities for Python development focused on
 reducing boilerplate while improving type safety and readability. Each
 release is tested thoroughly on each supported Python version from 3.7*
-to 3.14.
+to 3.15.
 
 *Maybe it is time to consider updating if you are still using Python 3.7.
 
@@ -108,13 +109,15 @@ Attributes are declared explicitly at the class level. Despite this,
 flexibility remains, for example:
 
 ```python
-point = Point(69, '420')  # int, str
+point = Point(69, 420)  # int, int
 point.x == 69.0
 point.y == 420.0
 ```
 
-When types do not match, `AttriBox` attempts casting before raising an
-error. Same ergonomics. Stronger guarantees.
+When types do not match, `AttriBox` converts what converts without loss,
+as an `int` to a `float`, and refuses the rest: `Point(69, '420')` raises
+`TypeException`, since no string is ever parsed. Same ergonomics. Stronger
+guarantees.
 
 Note that `Point` above is a plain class: both `AttriBox` and `Field`
 are ordinary descriptors and work on any class. The `BaseObject` base
@@ -168,7 +171,7 @@ from worktoy.core.sentinels import THIS
 from worktoy.dispatch import overload
 from worktoy.desc import AttriBox
 
-if TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:  # pragma: no cover, no mutate
   from typing import Self
 
 
@@ -316,10 +319,11 @@ class Point:
   def __init__(self, *args, ) -> None: ...  # Implementation as before
 ```
 
-Both improve clarity. But in both cases `Point.x` and `Point.y` will raise
-`AttributeError`. The presence of `x` and `y` becomes visible only after
-instantiation. At this point, they are just attributes of the instance, not
-of the class. Setting during `__init__` makes no difference compared to
+Both improve clarity, but neither makes `x` and `y` part of the class.
+With annotations alone, `Point.x` raises `AttributeError`; with
+`__slots__`, `Point.x` is a bare slot that knows nothing of the type.
+Either way the values appear only once `__init__` sets them, as attributes
+of the instance, and setting them there makes no difference compared to
 setting them anywhere else. Structure remains implicit.
 
 With **worktoy** attributes are an essential part of the class structure

{worktoy-1.0.1.dev1 → worktoy-1.1.0.dev1}/README.md

@@ -4,12 +4,12 @@
 [![PyPI version](https://img.shields.io/pypi/v/worktoy)](https://pypi.org/project/worktoy/)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-# worktoy v1.0.1-dev1 (development build)
+# worktoy v1.1.0-dev1 (development build)
 
 **worktoy** provides utilities for Python development focused on
 reducing boilerplate while improving type safety and readability. Each
 release is tested thoroughly on each supported Python version from 3.7*
-to 3.14.
+to 3.15.
 
 *Maybe it is time to consider updating if you are still using Python 3.7.
 
@@ -80,13 +80,15 @@ Attributes are declared explicitly at the class level. Despite this,
 flexibility remains, for example:
 
 ```python
-point = Point(69, '420')  # int, str
+point = Point(69, 420)  # int, int
 point.x == 69.0
 point.y == 420.0
 ```
 
-When types do not match, `AttriBox` attempts casting before raising an
-error. Same ergonomics. Stronger guarantees.
+When types do not match, `AttriBox` converts what converts without loss,
+as an `int` to a `float`, and refuses the rest: `Point(69, '420')` raises
+`TypeException`, since no string is ever parsed. Same ergonomics. Stronger
+guarantees.
 
 Note that `Point` above is a plain class: both `AttriBox` and `Field`
 are ordinary descriptors and work on any class. The `BaseObject` base
@@ -140,7 +142,7 @@ from worktoy.core.sentinels import THIS
 from worktoy.dispatch import overload
 from worktoy.desc import AttriBox
 
-if TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:  # pragma: no cover, no mutate
   from typing import Self
 
 
@@ -288,10 +290,11 @@ class Point:
   def __init__(self, *args, ) -> None: ...  # Implementation as before
 ```
 
-Both improve clarity. But in both cases `Point.x` and `Point.y` will raise
-`AttributeError`. The presence of `x` and `y` becomes visible only after
-instantiation. At this point, they are just attributes of the instance, not
-of the class. Setting during `__init__` makes no difference compared to
+Both improve clarity, but neither makes `x` and `y` part of the class.
+With annotations alone, `Point.x` raises `AttributeError`; with
+`__slots__`, `Point.x` is a bare slot that knows nothing of the type.
+Either way the values appear only once `__init__` sets them, as attributes
+of the instance, and setting them there makes no difference compared to
 setting them anywhere else. Structure remains implicit.
 
 With **worktoy** attributes are an essential part of the class structure

{worktoy-1.0.1.dev1 → worktoy-1.1.0.dev1}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = 'setuptools.build_meta'
 
 [project]
 name = "worktoy"
-version = "1.0.1-dev1"
+version = "1.1.0-dev1"
 authors = [
     { name = "Asger Jon Vistisen", email = "asgerjon2@gmail.com" },
 ]
@@ -22,6 +22,7 @@ classifiers = [
     'Programming Language :: Python :: 3.12',
     'Programming Language :: Python :: 3.13',
     'Programming Language :: Python :: 3.14',
+    'Programming Language :: Python :: 3.15',
     "Programming Language :: Python :: Implementation :: CPython",
     "License :: OSI Approved :: Apache Software License",
     "Operating System :: OS Independent",
@@ -40,9 +41,11 @@ test = [
     'pytest>=9.0.2',
     'pytest-cov>=7.0.0',
 ]
+#  The same packages as docs/requirements.txt. markwork brings Pygments.
 docs = [
     'sphinx>=7.0.0',
-    'pygments>=2.19.2',
+    'furo>=2024.1',
+    'markwork>=0.1.0',
 ]
 dev = [
     'icecream>=2.1.8',
@@ -54,13 +57,6 @@ dev = [
 [tool.setuptools.package-data]
 worktoy = ["py.typed"]
 
-[tool.coverage.run]
-omit = [
-    # Pre-PEP 634 fallback. Unreachable on 3.14 where coverage
-    # runs; exercised by unittest on <3.10.
-    "tests/test_ezdata/_match_args_legacy_helpers.py",
-]
-
 # pytest configuration lives here rather than in a root 'pytest.ini' so
 # the repository root stays uncluttered. pytest auto-discovers this
 # table, so no '-c' flag is needed locally or in CI.

{worktoy-1.0.1.dev1 → worktoy-1.1.0.dev1}/src/worktoy/__init__.py

@@ -34,12 +34,21 @@ chain.
   descriptors.
 - work_test: Testing support, providing 'BaseTest' and the random-data
   samplers used across the test suite.
+
+Nested classes: 'worktoy' is designed around custom metaclasses and the
+class statements they build, not around classes nested in the body of
+another class. A nested class may well work, but some edge cases are not
+supported. One example is a nested class with the same base as the
+enclosing class: a 'THIS[Parent]' reference in the enclosing body places
+its clone on the next subclass created of the class holding the
+descriptor, 'Parent' or a base of it, which is then the nested class,
+and the enclosing class is left without the decoration.
 """
 #  Apache-2.0 license
 #  Copyright (c) 2025-2026 Asger Jon Vistisen
 from __future__ import annotations
 
-__version__ = '1.0.1-dev1'
+__version__ = '1.1.0-dev1'
 
 from . import utilities
 from . import waitaminute

{worktoy-1.0.1.dev1 → worktoy-1.1.0.dev1}/src/worktoy/core/__init__.py

@@ -6,18 +6,21 @@ metaclass framework and the descriptor layer build on.
 - Object
 - ContextInstance, ContextOwner
 - sentinels
+- control_flow
 """
 #  Apache-2.0 license
 #  Copyright (c) 2025-2026 Asger Jon Vistisen
 from __future__ import annotations
 
+from ._meta_type import MetaType
 from . import sentinels
+from . import control_flow
 from ._instance_owner import ContextInstance, ContextOwner
-from ._meta_type import MetaType
 from ._object import Object
 
 __all__ = [
   'sentinels',
+  'control_flow',
   'ContextInstance',
   'ContextOwner',
   'MetaType',

{worktoy-1.0.1.dev1 → worktoy-1.1.0.dev1}/src/worktoy/core/_instance_owner.py

@@ -8,17 +8,24 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-if TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:  # pragma: no cover, no mutate
   from typing import Any
 
 
 class ContextInstance:
-  """Descriptor that returns the currently active instance.
-
-  When accessed on a class, returns the descriptor itself. When
-  accessed on an 'Object' instance, returns the top-of-stack
-  instance via 'Object.getContextInstance'. Raises
-  'WithoutException' if no context frame is active.
+  """
+  Inside the hooks of a descriptor based on 'Object', 'self.instance'
+  must give the instance of the access in progress, the object the
+  attribute is read from, written to or deleted from. The same name read
+  through the class must give something harmless, and the descriptor
+  machinery must never depend on it, since a subclass may shadow it.
+
+  Implementation
+  --------------
+
+  Through the class, the descriptor returns itself. Through an 'Object',
+  it returns 'getContextInstance()', which reads the top frame of the
+  context stack, and fails outside an access as that method describes.
   """
 
   # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
@@ -32,12 +39,16 @@ class ContextInstance:
 
 
 class ContextOwner:
-  """Descriptor that returns the currently active owner class.
+  """
+  Inside the hooks of a descriptor based on 'Object', 'self.owner' must
+  give the owning class of the access in progress.
+
+  Implementation
+  --------------
 
-  When accessed on a class, returns the descriptor itself. When
-  accessed on an 'Object' instance, returns the top-of-stack owner
-  via 'Object.getContextOwner'. Raises 'WithoutException' if no
-  context frame is active.
+  Through the class, the descriptor returns itself. Through an 'Object',
+  it returns 'getContextOwner()', which reads the top frame of the
+  context stack, and fails outside an access as that method describes.
   """
 
   # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #