GitHub - emcd/python-classcore

🏭 A Python library package which provides foundational class factories and decorators for providing classes with attributes immutability and concealment and other custom behaviors.

Key Features ⭐

🔧 Class Customization: Composable decorators and metaclasses providing classes with customized behaviors.

🔒 Attribute Immutability: Standard collection of metaclasses and decorators to provide immutability for class and instance attributes, with support for selective mutability via names, regexes, or predicates.

👁️ Attribute Concealment: Standard collection of metaclasses and decorators to provide concealment for class and instance attributes, with support for selective visibility via names, regexes, or predicates.

📚 Dataclass Integration: Decorators like dataclass_with_standard_behaviors make standard Python dataclasses with immutability and concealment. (Unlike dataclass( frozen = True ), attributes can still be manipulated via __post_init__ when one of these decorators is applied.)

🧩 Protocol Support: Immutable protocol classes for nominal and structural subtyping, compatible with typing.Protocol. Immutability and concealment are inherited by subclassed implementations of these protocols.

🗂️ Module Reclassification: Apply immutability and concealment to entire modules.

Installation 📦

Method: Install Python Package

Install via uv pip command:

uv pip install classcore

Or, install via pip:

pip install classcore

Note on Immutability 📢

Enforcement of immutability is quite difficult in Python. While this library encourages immutability by default, it can be circumvented by anyone who has intermediate knowledge of Python machinery and who is determined to circumvent the immutability. Use the library in the spirit of making programs safer, but understand that it cannot truly prevent unwanted state tampering.

Examples 💡

Please see the examples directory for greater detail.

Standard Behaviors 🔒

Produce classes which have immutable and concealed attributes and whose instances have immutable and concealed attributes. Can be normal classes, dataclasses, protocol classes, etc....

from dataclasses import field
from math import sqrt

from classcore.standard import DataclassObject

class Point2d( DataclassObject ):
    x: float
    y: float
    hypotenuse: float = field( init = False )
    def __post_init__( self ) -> None:
        x, y = self.x, self.y
        self.hypotenuse = sqrt( x*x + y*y )

Point2d.x = 3     # ❌ Error, immutable class attribute.
point = Point2d( x = 3, y = 4 )
point.x = 42      # ❌ Error, immutable instance attribute.
point.hypotenuse  # Result: 5
dir( point )      # Result: ['hypotenuse', 'x', 'y']

Decorate classes so that their instances will have immutable and concealed attributes.

from dataclasses import field
from math import sqrt

from classcore.standard import dataclass_with_standard_behaviors

@dataclass_with_standard_behaviors( )
class Point2d:
    x: float
    y: float
    hypotenuse: float = field( init = False )
    def __post_init__( self ) -> None:
        x, y = self.x, self.y
        self.hypotenuse = sqrt( x*x + y*y )

point = Point2d( x = 5, y = 12 )
point.x = 42      # ❌ Error, immutable instance attribute.
point.hypotenuse  # Result: 13
dir( point )      # Result: ['hypotenuse', 'x', 'y']

Module Reclassification 📦

Make modules (or entire packages) immutable to prevent direct modification of their attributes and to present only their public attributes via dir.

from classcore.standard import reclassify_modules

reclassify_modules( __name__, recursive = True )

Use Cases 🎯

• 📊 Data Transfer Objects: Ensure data integrity with immutable DTOs.
• 🏛️ API Interfaces: Define stable, well-controlled interfaces.
• 🧩 Plugin Systems: Plugin systems with controlled extension points.
• 📦 Frameworks: Frameworks with controlled extension and modification.

Contribution 🤝

Contribution to this project is welcome! However, it must follow the code of conduct for the project.

Please file bug reports and feature requests in the issue tracker or submit pull requests to improve the source code or documentation.

For development guidance and standards, please see the development guide.

Additional Indicia

Other Projects by This Author 🌟

• python-absence (absence on PyPI)

  🕳️ A Python library package which provides a sentinel for absent values - a falsey, immutable singleton that represents the absence of a value in contexts where None or False may be valid values.

• python-accretive (accretive on PyPI)

  🌌 A Python library package which provides accretive data structures - collections which can grow but never shrink.

• python-detextive (detextive on PyPI)

  🕵️ A Python library which provides consolidated text detection capabilities for reliable content analysis. Offers MIME type detection, character set detection, and line separator processing.

• python-dynadoc (dynadoc on PyPI)

  📝 A Python library package which bridges the gap between rich annotations and automatic documentation generation with configurable renderers and support for reusable fragments.

• python-falsifier (falsifier on PyPI)

  🎭 A very simple Python library package which provides a base class for falsey objects - objects that evaluate to False in boolean contexts.

• python-frigid (frigid on PyPI)

  🔒 A Python library package which provides immutable data structures - collections which cannot be modified after creation.

• python-icecream-truck (icecream-truck on PyPI)

  🍦 Flavorful Debugging - A Python library which enhances the powerful and well-known icecream package with flavored traces, configuration hierarchies, customized outputs, ready-made recipes, and more.

• python-librovore (librovore on PyPI)

  🐲 Documentation Search Engine - An intelligent documentation search and extraction tool that provides both a command-line interface for humans and an MCP (Model Context Protocol) server for AI agents. Search across Sphinx and MkDocs sites with fuzzy matching, extract clean markdown content, and integrate seamlessly with AI development workflows.

• python-mimeogram (mimeogram on PyPI)

  📨 A command-line tool for exchanging collections of files with Large Language Models - bundle multiple files into a single clipboard-ready document while preserving directory structure and metadata... good for code reviews, project sharing, and LLM interactions.