extensionmethods 0.1.0__py3-none-any.whl

extensionmethods/__init__.py

@@ -0,0 +1,12 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from .extensions import extension
+
+try:
+    __version__ = version("extensionmethods")
+except PackageNotFoundError:
+    __version__ = "noinstall"
+
+__all__ = [
+    "extension",
+]

extensionmethods/extensions.py

@@ -0,0 +1,44 @@
+from functools import wraps
+from typing import Any, Callable, Generic, Type, TypeVar
+
+T = TypeVar("T")
+
+
+class ExtensionDecorator(Generic[T]):
+    def __init__(self, func: Callable[..., Any], args, kwargs, to: Type[T]):
+        self._func = func
+        self._to = to
+        self._args = args
+        self._kwargs = kwargs
+
+    def __call__(self, _: Any) -> Any:
+        raise NotImplementedError("Don't call an extension method directly.")
+
+    def __ror__(self, other: T) -> Any:
+        if not isinstance(other, self._to):
+            raise TypeError(
+                f"Extension '{self._func.__name__}' can only be used on '{self._to.__name__}', "
+                f"not '{type(other).__name__}'"
+            )
+
+        return self._func(other, *self._args, **self._kwargs)
+
+
+class ExtensionDecoratorFactory(Generic[T]):
+    def __init__(self, func: Callable[..., Any], to: Type[T]):
+        self._func = func
+        self._to = to
+
+        wraps(func)(self)
+
+    def __call__(self, *args, **kwargs) -> ExtensionDecorator[T]:
+        return ExtensionDecorator(self._func, args, kwargs, self._to)
+
+
+def extension(
+    *, to: Type[T]
+) -> Callable[[Callable[..., Any]], ExtensionDecoratorFactory[T]]:
+    def wrapper(func: Callable[..., Any]) -> ExtensionDecoratorFactory[T]:
+        return ExtensionDecoratorFactory(func, to)
+
+    return wrapper

extensionmethods-0.1.0.dist-info/METADATA

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: extensionmethods
+Version: 0.1.0
+Summary: Add your description here
+Author-email: Pim Mostert <pim.mostert@pimmostert.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Pim-Mostert/extensionmethods
+Project-URL: Issues, https://github.com/Pim-Mostert/extensionmethods/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# extensionmethods
+
+Mimics C#-style extension methods in Python.
+
+`extensionmethods` is a tiny package that lets you “attach” functions to existing types without modifying their source code, enabling method-like syntax, better chaining, and cleaner separation of optional dependencies.
+
+- [extensionmethods](#extensionmethods)
+  - [Example usage](#example-usage)
+  - [Type safety and type checking](#type-safety-and-type-checking)
+  - [Installation](#installation)
+  - [Why use extension methods?](#why-use-extension-methods)
+    - [Readability through chaining](#readability-through-chaining)
+    - [Modularity and dependency isolation](#modularity-and-dependency-isolation)
+  - [Known caveats](#known-caveats)
+    - [IDE type hints may be misleading](#ide-type-hints-may-be-misleading)
+    - [Uses the `|` operator (`__ror__`)](#uses-the--operator-__ror__)
+  - [License](#license)
+
+
+## Example usage
+
+In C#, you can add methods to existing types:
+
+```csharp
+public static class IntExtensions
+{
+    public static int Double(this int x)
+    {
+        return x * 2;
+    }
+}
+
+int result = 7.Double();
+```
+
+You get method syntax without modifying `int`.
+
+With the `extensionmethods` package you can achieve similiar functionality like so:
+
+```python
+from extensionmethods import extension
+
+@extension(to=int)
+def double(x: int) -> int:
+    return x * 2
+
+result = 7 | double()
+print(result)  # 14
+```
+
+With parameters:
+
+```python
+@extension(to=int)
+def add_then_multiply(x: int, to_add: int, to_multiply: int) -> int:
+    return (x + to_add) * to_multiply
+
+result = 7 | add_then_multiply(11, 3)
+print(result)  # 54
+```
+
+The value on the left side becomes the first argument of the function.
+
+## Type safety and type checking
+
+The extension methods are type-aware.
+
+When you declare an extension, you bind it to a specific type:
+
+```python
+@extension(to=int)
+def double(x: int) -> int:
+    return x * 2
+```
+
+This gives you safety at two levels:
+
+- **IDE / static type checking**
+    Type checkers and editors can detect incorrect usage:
+
+    ```python
+    "hello" | double()  # type error
+    ```
+
+    Your IDE (e.g. VS Code) can flag this because the extension is declared for `int`, not `str`.
+
+- **Runtime enforcement**
+
+    Even if type checking is bypassed, the library validates the type at runtime:
+
+    ```python
+    >>> "hello" | double()
+    TypeError: Extension 'double' can only be used on 'int', not 'str'
+    ```
+
+## Installation
+
+Using **pip**:
+
+```bash
+pip install extensionmethods
+```
+
+Using **uv**:
+
+```bash
+uv pip install extensionmethods
+```
+
+## Why use extension methods?
+
+### Readability through chaining
+
+Instead of nested calls:
+
+```python
+result = normalize(scale(center(data)))
+```
+
+You can express the same flow step-by-step:
+
+```python
+result = data | center() | scale() | normalize()
+```
+
+This reads left-to-right and mirrors how data is conceptually transformed.
+
+### Modularity and dependency isolation
+
+Suppose you maintain a core class:
+
+```python
+class Dataset:
+    ...
+```
+
+You want export helpers:
+
+- `to_pandas()`
+- `to_numpy()`
+- `to_torch()`
+
+If you put these methods directly on `Dataset`, your core package must depend on `pandas`, `numpy`, and `torch`.
+
+Instead, keep the core dependency-free:
+
+```python
+# core package
+class Dataset:
+    ...
+```
+
+Then provide optional extensions:
+
+```python
+# dataset_pandas package
+import pandas as pd
+from extensionmethods import extension
+from core import Dataset
+
+@extension(to=Dataset)
+def to_pandas(ds: Dataset) -> pd.DataFrame:
+    ...
+```
+
+Usage:
+
+```python
+import dataset_pandas  # registers the extension
+
+df = dataset | to_pandas()
+```
+
+Now:
+
+- The core package has zero heavy dependencies
+- Users only install what they need
+- Functionality stays logically grouped
+
+## Known caveats
+
+### IDE type hints may be misleading
+
+Editors like VS Code may show hover/type information for the decorator wrapper, not the original function.
+
+```python
+@extension(to=int)
+def double(x: int) -> int:
+    return x * 2
+```
+
+Hovering `double` may not show the expected signature `(x: int) -> int`, but instead `(function) double: ExtensionDecoratorFactory[int]`.
+
+### Uses the `|` operator (`__ror__`)
+
+The system works by overriding the right-side bitwise OR operator.
+
+```python
+result = value | extension_call()
+```
+
+This only works if the left-hand type does not fully consume the `|` operator itself.
+
+For example, sets already use `|`:
+
+```python
+{1, 2} | {3}   # set union
+```
+
+If a type defines its own `__or__` in a way that prevents fallback to `__ror__`, the extension method will not run.
+
+## License
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.

extensionmethods-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+extensionmethods/__init__.py,sha256=GAyBMLVqiT4ASpVxDgxY17deN63Z47A5T7dqquM2unA,239
+extensionmethods/extensions.py,sha256=tKudbhaUxfsQyUSJKnsnWYE6IPy8D1b0D-QYn3E0-F4,1349
+extensionmethods-0.1.0.dist-info/licenses/LICENSE,sha256=PPj-m0UNCQgpVhkr-w1SAqbEUR8M0Mw3ANB4myKxt2E,1067
+extensionmethods-0.1.0.dist-info/METADATA,sha256=k8pNs-Vuen9E1x381Jtr_7bcWfmTLqn-4IZrSpLVRJw,5194
+extensionmethods-0.1.0.dist-info/WHEEL,sha256=YLJXdYXQ2FQ0Uqn2J-6iEIC-3iOey8lH3xCtvFLkd8Q,91
+extensionmethods-0.1.0.dist-info/top_level.txt,sha256=t4mdhmA_07HZDmnLqfr-4PYjbe2sAkVJ3NULiaR6nx0,17
+extensionmethods-0.1.0.dist-info/RECORD,,

extensionmethods-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (81.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

extensionmethods-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pim Mostert
+
+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.

extensionmethods-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+extensionmethods