Skip to main content
Change of provenance

The repository or configuration that created this release differ from a previous release. View details.

Pre-release

This release is a pre-release and may not be stable for production use.

wakatime Tokens codecov PyPI version License: Apache 2.0

worktoy v1.2.0-dev0 (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.15.

*Maybe it is time to consider updating if you are still using Python 3.7.

Table of Contents

Installation

Install with pip:

pip install worktoy

Python Is Easy. Too Easy!

What enables effortless prototyping does not guarantee the scalable structure serious applications demand.

Introducing worktoy.

A structural layer for Python that adds deliberate constraints without sacrificing ergonomics. It brings the architectural discipline of statically typed languages to dynamic Python.

Build the GUI. Build the logic. Build the architecture. All in Python.

'Trust-Me-Bro'-Typing

class Point:
  def __init__(self, x: float = 0.0, y: float = 0.0) -> None:
    self.x = x
    self.y = y

The above code is perfectly valid Python, it even includes types. Or does it? Those float annotations are not there at runtime. Basically, it is 'trust-me-bro'-typing. Point('breh', None) will happily create a Point object.

Instead:

from worktoy.desc import AttriBox


class Point:
  x = AttriBox[float](0.0)
  y = AttriBox[float](0.0)

  def __init__(self, x: float = 0.0, y: float = 0.0) -> None:
    self.x = x
    self.y = y

When AttriBox says float it enforces float at runtime. Attributes are declared explicitly at the class level. Despite this, flexibility remains, for example:

point = Point(69, 420)  # int, int
point.x == 69.0
point.y == 420.0

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 shown in the examples below is required only for the @overload machinery, not for declarative attributes.

The Python Parsing Situation Is Crazy

Python is not always easy though. Consider the Point implementation under discussion. Suppose we wanted a flexible constructor. One that supports instantiation on:

  • a pair of float objects
  • a complex number
  • another Point object

That is possible in Python, for example:

class Point:

  def __init__(self, *args, ) -> None:
    if len(args) == 2:
      self.x = float(args[0])
      self.y = float(args[1])
    elif len(args) == 1:
      if isinstance(args[0], complex):
        self.x = args[0].real
        self.y = args[0].imag
      elif isinstance(args[0], type(self)):
        self.x = args[0].x
        self.y = args[0].y
    else:
      raise TypeError('Invalid arguments')

Possible? Sure, but look at that syntactic broccoli! Conditional branches. Growing complexity. Manual parsing. Long gone are those happy days of effortless coding.

But it does not have to be like this. Introducing @overload:

from __future__ import annotations

from typing import TYPE_CHECKING

from worktoy.mcls import BaseObject
from worktoy.core.sentinels import THIS
from worktoy.dispatch import overload
from worktoy.desc import AttriBox

if TYPE_CHECKING:  # pragma: no cover, no mutate
  from typing import Self


class Point(BaseObject):
  x = AttriBox[float](0.0)
  y = AttriBox[float](0.0)

  @overload(float, float)
  def __init__(self, x: float, y: float) -> None:
    self.x = x
    self.y = y

  @overload(complex)
  def __init__(self, z: complex) -> None:
    self.x = z.real
    self.y = z.imag

  @overload(THIS)  # THIS = the enclosing class (matches an instance of it)
  def __init__(self, other: Self) -> None:
    self.x = other.x
    self.y = other.y

  @overload()
  def __init__(self, ) -> None:
    pass

Each new signature requires one new overloaded function. No more painful parsing of *args. All of this just works. Actually.

"Show Don't Tell" Is for Stories, not for Code!

When reading code, you look for declarations. For where symbols are defined. For where meaning begins.

Narrative storytelling is different. The method by which information is conveyed is itself part of the artistic expression. The way information is revealed is frequently as important as the information itself. In Clair Obscur: Expedition 33, the horror of the Gommage unfolds gradually until Sophie disappears from Gustave's arms. The imperative subtlety grants the story its emotional impact.

In code, the declaration is the point! In matters of code, I want declarations. I don't want foreshadowing. I don't want subtlety. I don't want subversion of expectations. I want declarations.

Anyway, what were we talking about? Right, figure out what point.r is from the code below:

class Point:
  def __init__(self, *args, ) -> None:
    if len(args) == 2:
      self.x = float(args[0])
      self.y = float(args[1])
    elif len(args) == 1:
      if isinstance(args[0], complex):
        self.x = args[0].real
        self.y = args[0].imag
      elif isinstance(args[0], type(self)):
        self.x = args[0].x
        self.y = args[0].y
    else:
      raise TypeError('Invalid arguments')

  @property
  def r(self) -> float:
    return (self.x ** 2 + self.y ** 2) ** 0.5

Great, you found it. Well, you found what it does, and you inferred it. This is imperative declaration. In Python, this is fine. It is much worse in other languages. Anyway, here is the alternative provided by worktoy: Field.

from worktoy.desc import Field


class Point(BaseObject):
  x = AttriBox[float](0.0)
  y = AttriBox[float](0.0)

  r: Field[float] = Field()  # Straight up declaration!

  @overload(float, float)
  def __init__(self, x: float = 0.0, y: float = 0.0) -> None:
    self.x = x
    self.y = y

  @overload(complex)
  def __init__(self, z: complex) -> None:
    self.x = z.real
    self.y = z.imag

  @overload(THIS)  # THIS = the enclosing class (matches an instance of it)
  def __init__(self, other: Self) -> None:
    self.x = other.x
    self.y = other.y

  @overload()
  def __init__(self, ) -> None:
    pass

  @r.GET  # Straight up declaration of something called 'GET'.
  def _getR(self) -> float:
    return (self.x ** 2 + self.y ** 2) ** 0.5

The r attribute is declared first. Next, the @r.GET declares that the method implementing the get operation comes next. The structure is visible separately from the behaviour.

Static Discipline

In plain Python, attributes assigned in __init__ are closer to dictionary entries than declared structure.

class Point:
  def __init__(self, x: float = 0.0, y: float = 0.0) -> None:
    self.x = x
    self.y = y

Inspecting the class reveals nothing about x or y. They do not exist at the class level. They are created at runtime on the instance. Two common remedies are __slots__ and annotations:

class Point:
  __slots__ = ('x', 'y')

  def __init__(self, *args) -> None: ...

or

class Point:
  x: float
  y: float

  def __init__(self, *args, ) -> None: ...  # Implementation as before

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 on par with methods.

class Point(BaseObject):
  x = AttriBox[float](0.0)
  y = AttriBox[float](0.0)

  #  Implementation as before

Now x and y are declared at the class level, making them visible, inspectable and enforced. They are more than just keys in an instance dictionary. They are structural elements of the class. In plain Python, instances define structure. Here, the class does.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the style rules and development setup.

License

worktoy is released under the Apache License 2.0 (Apache-2.0). See LICENSE for the full text.

Metadata

Release files for worktoy 1.2.0.dev0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Change of provenance

The repository or configuration that created these release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Source distribution (sdist)

Source distribution for worktoy 1.2.0.dev0
File Size Uploaded Provenance Actions
worktoy-1.2.0.dev0.tar.gz 248.2 kB With provenance Details for worktoy-1.2.0.dev0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for worktoy 1.2.0.dev0
File Interpreter ABI Platform Actions
worktoy-1.2.0.dev0-py3-none-any.whl Python 3 none any Details for worktoy-1.2.0.dev0-py3-none-any.whl

Total release size: 603.3 kB

Release files / worktoy-1.2.0.dev0.tar.gz

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL worktoy-1.2.0.dev0.tar.gz
Size 248.2 kB
Tags Source
SHA-256 checksum
How to use checksums
c44f2ec321bd19e0b1d211944c8a80fa5cbf18a7c91590fa0c17f10774f2b6a9
BLAKE2b-256 checksum
How to use checksums
92f678d5ef450727a6cafe7e6d27d66eb06fbb0fa2303a7aa1f0730e02ce4f45
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / worktoy-1.2.0.dev0-py3-none-any.whl

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL worktoy-1.2.0.dev0-py3-none-any.whl
Size 355.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
67fc90db6922d955ad07ae92b41a763acc25cc07b0c6ae8b5dbe3095f49cc137
BLAKE2b-256 checksum
How to use checksums
19d1a099d5c5d9a52d69a4fe5c805cdd601a3bb47f4ae9664c51121894ba7aee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for worktoy 1.2.0.dev0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Change of provenance

The configuration that created this release differs from a previous release.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Select from 2 files

Attestation for worktoy-1.2.0.dev0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page