haiway 0.20.1__tar.gz → 0.21.1__tar.gz

{haiway-0.20.1 → haiway-0.21.1}/Makefile

@@ -10,7 +10,7 @@ TESTS_PATH := tests
 -include .env
 
 ifndef UV_VERSION
-	UV_VERSION := 0.7.5
+	UV_VERSION := 0.7.6
 endif
 
 .PHONY: uv_check venv sync update format lint test release

{haiway-0.20.1 → haiway-0.21.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: haiway
-Version: 0.20.1
+Version: 0.21.1
 Summary: Framework for dependency injection and state management within structured concurrency model.
 Project-URL: Homepage, https://miquido.com
 Project-URL: Repository, https://github.com/miquido/haiway.git
@@ -42,13 +42,17 @@ Requires-Dist: pytest-cov~=6.1; extra == 'dev'
 Requires-Dist: pytest~=8.3; extra == 'dev'
 Requires-Dist: ruff~=0.11; extra == 'dev'
 Provides-Extra: opentelemetry
-Requires-Dist: opentelemetry-api; extra == 'opentelemetry'
-Requires-Dist: opentelemetry-exporter-otlp-proto-grpc; extra == 'opentelemetry'
-Requires-Dist: opentelemetry-sdk; extra == 'opentelemetry'
+Requires-Dist: opentelemetry-api~=1.33; extra == 'opentelemetry'
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc~=1.33; extra == 'opentelemetry'
+Requires-Dist: opentelemetry-sdk~=1.33; extra == 'opentelemetry'
 Description-Content-Type: text/markdown
 
 # 🚗 haiway 🚕 🚚 🚙
 
+![Python Version](https://img.shields.io/badge/Python-3.12+-blue)
+![License](https://img.shields.io/badge/License-MIT-green)
+![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/miquido/haiway?utm_source=oss&utm_medium=github&utm_campaign=miquido%2Fhaiway&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
+
 haiway is a framework designed to facilitate the development of applications using the functional programming paradigm combined with structured concurrency concepts. Unlike traditional object-oriented frameworks, haiway emphasizes immutability, pure functions, and context-based state management, enabling developers to build scalable and maintainable applications. By leveraging context managers combined with context vars, haiway ensures safe state propagation in concurrent environments and simplifies dependency injection through function implementation propagation.
 
 ## 🖥️ Install

{haiway-0.20.1 → haiway-0.21.1}/README.md

@@ -1,5 +1,9 @@
 # 🚗 haiway 🚕 🚚 🚙
 
+![Python Version](https://img.shields.io/badge/Python-3.12+-blue)
+![License](https://img.shields.io/badge/License-MIT-green)
+![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/miquido/haiway?utm_source=oss&utm_medium=github&utm_campaign=miquido%2Fhaiway&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
+
 haiway is a framework designed to facilitate the development of applications using the functional programming paradigm combined with structured concurrency concepts. Unlike traditional object-oriented frameworks, haiway emphasizes immutability, pure functions, and context-based state management, enabling developers to build scalable and maintainable applications. By leveraging context managers combined with context vars, haiway ensures safe state propagation in concurrent environments and simplifies dependency injection through function implementation propagation.
 
 ## 🖥️ Install

{haiway-0.20.1 → haiway-0.21.1}/guidelines/functionalities.md

@@ -1,25 +1,25 @@
 ## Functionalities
 
-haiway is a framework designed to facilitate the development of applications using the functional programming paradigm combined with structured concurrency concepts. Unlike traditional object-oriented frameworks, haiway emphasizes immutability, pure functions, and context-based state management, enabling developers to build scalable and maintainable applications. By leveraging context managers combined with context vars, haiway ensures safe state propagation in concurrent environments and simplifies dependency injection through function implementation propagation.
+Haiway is a framework designed to facilitate the development of applications using the functional programming paradigm combined with structured concurrency concepts. Unlike traditional object-oriented frameworks, Haiway emphasizes immutability, pure functions, and context-based state management, enabling developers to build scalable and maintainable applications. By leveraging context managers combined with context variables, Haiway ensures safe state propagation in concurrent environments and simplifies dependency injection through function implementation propagation.
 
-### Functional basics
+### Functional Basics
 
-Functional programming centers around creating pure functions - functions that have no side effects and rely solely on their inputs to produce outputs. This approach promotes predictability, easier testing, and better modularity. While Python is inherently multi-paradigm and not strictly functional, haiway encourages adopting functional principles where feasible to enhance code clarity and reliability.
+Functional programming centers around creating pure functions - functions that have no side effects and rely solely on their inputs to produce outputs. This approach promotes predictability, easier testing, and better modularity. While Python is inherently multi-paradigm and not strictly functional, Haiway encourages adopting functional principles where feasible to enhance code clarity and reliability.
 
 Key functional concepts:
 - Immutability: Data structures are immutable, preventing unintended side effects.
 - Pure Functions: Functions depend only on their inputs and produce outputs without altering external state.
 - Higher-Order Functions: Functions that can take other functions as arguments or return them as results.
 
-haiway balances functional purity with Python’s flexibility by allowing limited side effects when necessary, though minimizing them is recommended for maintainability.
+Haiway balances functional purity with Python's flexibility by allowing limited side effects when necessary, though minimizing them is recommended for maintainability.
 
-Instead of preparing objects with internal state and methods, haiway encourages creating structures containing sets of functions and providing state either through function arguments or contextually using execution scope state. Using explicit function arguments is the preferred method; however, some functionalities may benefit from contextual, broader accessible state.
+Instead of preparing objects with internal state and methods, Haiway encourages creating structures containing sets of functions and providing state either through function arguments or contextually using execution scope state. Using explicit function arguments is the preferred method; however, some functionalities may benefit from contextual, broader accessible state.
 
-### Preparing functionalities
+### Preparing Functionalities
 
-In haiway, functionalities are modularized into two primary components: interfaces and implementations This separation ensures clear contracts for functionalities, promoting modularity and ease of testing.
+In Haiway, functionalities are modularized into two primary components: interfaces and implementations. This separation ensures clear contracts for functionalities, promoting modularity and ease of testing.
 
-### Defining types
+### Defining Types
 
 Interfaces define the public API of a functionality, specifying the data types and functions it exposes without detailing the underlying implementation. Preparing functionality starts from defining associated types - data structures and function types.
 
@@ -40,9 +40,9 @@ class FunctionSignature(Protocol):
 
 In the example above, typing.Protocol is used to fully define the function signature, along with a custom structure serving as its argument. Function type names should emphasize the nature of their operations by using continuous tense adjectives, such as 'ElementCreating' or 'ValueLoading.'
 
-### Defining state
+### Defining State
 
-State represents the immutable data required by functionalities. It is propagated through contexts to maintain consistency and support dependency injection. haiway comes with a helpful base class `State` which utilizes dataclass-like transform combined with runtime type checking and immutability.
+State represents the immutable data required by functionalities. It is propagated through contexts to maintain consistency and support dependency injection. Haiway comes with a helpful base class `State` which utilizes dataclass-like transform combined with runtime type checking and immutability.
 
 ```python
 # state.py
@@ -60,7 +60,7 @@ class Functionality(State):
 
 This example shows a state required by the functionality as well as a container for holding function implementations. Both are intended to be propagated contextually to be accessible throughout the application and possibly altered when needed.
 
-### Defining implementation
+### Defining Implementation
 
 Implementations provide concrete behavior for the defined interfaces, ensuring that they conform to the specified contracts.
 
@@ -81,34 +81,15 @@ async def function_implementation(argument: FunctionArgument) -> None:
 # Factory function to instantiate the Functionality with its implementation
 def functionality_implementation() -> Functionality:
     return Functionality(function=function_implementation)
-
 ```
 
-In the example above, function_implementation is the concrete implementation of the previously declared function, and functionality_implementation is a factory method suitable for creating a full implementation of the Functionality.
+In the example above, function_implementation is a concrete implementation of the previously declared function, and functionality_implementation is a factory method suitable for creating a full implementation of the Functionality.
 
-Alternatively, instead of providing a factory method, some implementations may allow to define default values within state. This approach is also valid to implement and allows to skip explicit definitions of state by leveraging automatically created defaults.
+Alternatively, instead of providing a factory method, some implementations may allow defining default values within state. This approach is also valid to implement and allows skipping explicit definitions of state by leveraging automatically created defaults.
 
-### Defining calls
+### Classmethod Calls
 
-Calls act as intermediaries that invoke the function implementations within the appropriate context. This abstraction simplifies access to functionalities by hiding non-essential details and access to various required components.
-
-```python
-# calls.py
-from my_functionality.types import FunctionArgument
-from my_functionality.state import FunctionalityState, Functionality
-from haiway import ctx
-
-# Call function that invokes the functionality within the current context
-async def function_call(argument: FunctionArgument) -> None:
-    # Invoke the function implementation from the contextual state
-    await ctx.state(Functionality).function(argument=argument)
-```
-
-The example above shows a simple proxy call that accesses the required contextual details of the implementation.
-
-### Classmethod calls
-
-When possible, preferred way of defining calls is to put them within the functionality state type as class methods. This approach allows easier access to desired functions and improves egonomy over the free functions access.
+Calls act as intermediaries that invoke the function implementations within the appropriate context. This abstraction simplifies access to functionalities by hiding non-essential details and access to various required components. When possible, the preferred way of defining calls is to put them within the functionality state type as class methods. This approach allows easier access to desired functions and improves ergonomics over the free functions access.
 
 ```python
 # state.py - revisited
@@ -116,22 +97,22 @@ When possible, preferred way of defining calls is to put them within the functio
 class Functionality(State):
     # define function call as a class method
     @classmethod
-    def function_call(cls, argument: FunctionArgument) -> None:
+    async def function_call(cls, argument: FunctionArgument) -> None:
         # Invoke the function implementation from the contextual state
         await ctx.state(cls).function(argument=argument)
 
     function: FunctionSignature
 ```
 
-The approach presented above is an equivalent of previous `function_call` defined as a free function. Keeping it within the functionality interface class allows streamlined access and better control over the calls.
+Keeping it within the functionality interface class allows streamlined access and better control over the calls.
 
-### Using implementation
+### Using Implementation
 
-To utilize the defined functionalities within an application, contexts must be established to provide the necessary state and implementations. Below is an example of how to integrate haiway functionalities into an application.
+To utilize the defined functionalities within an application, contexts must be established to provide the necessary state and implementations. Below is an example of how to integrate Haiway functionalities into an application.
 
 ```python
 # application.py
-from my_functionality import functionality_implementation, function, FunctionalityState
+from my_functionality import functionality_implementation, Functionality, FunctionalityState
 from haiway import ctx
 
 # Example application function utilizing the functionality
@@ -143,42 +124,16 @@ async def application_function(argument: FunctionArgument) -> None:
         FunctionalityState(parameter="ExampleParameter")
     ):
         # Execute the functionality using the predefined helper
-        await function_call(FunctionArgument(value="SampleValue"))
+        await Functionality.function_call(FunctionArgument(value="SampleValue"))
 ```
 
 Going through all of these layers may seem unnecessary at first, but in the long term, it creates a robust, modular system that is easy to manage and work with.
 
-### Flexible arguments
-
-When a function defined within the functionality is intended to utilize contextual state it might be beneficial to allow it to take any additional keyword arguments that would be used to update contextual state within the implementation. This approach allows to update contextual state locally, only for a single function call without propagating the change deeply into call tree.
-
-```python
-...
-
-# function signature allowing extra arguments
-@runtime_checkable
-class FunctionSignature(Protocol):
-    async def __call__(self, argument: FunctionArgument, **extra: Any) -> None: ...
-
-...
-
-# function implementation utilizing extra arguments to update local state
-async def function_implementation(argument: FunctionArgument, **extra: Any) -> None:
-    # Retrieve 'parameter' from the current context's state updated with extra arguments
-    parameter = ctx.state(FunctionalityState).updated(**extra).parameter
-    ...
-
-```
-
-haiway `State` types allow to create object copies with updated attributes by using `updated` method. The updated object is a swallow copy of the original object allowing to change the state only in local context without affecting other users of that state. When there are no changes to be applied no copy is created. Additionally the `updated` method skips all unnecessary arguments to handle described case without additional code required. However, there is always risk of name collisions, this approach should be carefully considered to avoid any potential issues.
-
-Additionally, this approach allows to utilize additional, implementation specific arguments, hidden beneatch the usual function signatures.
-
 ## Example
 
-To better understand the whole idea we can take a look at more concrete example of a notes management functionality:
+To better understand the whole idea, we can take a look at a more concrete example of a notes management functionality:
 
-First we define some basic types required by our functionality - management functions signatures and the note itself.
+First, we define some basic types required by our functionality - management functions signatures and the note itself.
 
 ```python
 # notes/types.py
@@ -208,9 +163,9 @@ Then we can define the state holding our functions and defining some context.
 
 ```python
 # notes/state.py
-from notes.types import NoteCreating, NoteUpdating
-
-from haiway import State
+from notes.types import NoteCreating, NoteUpdating, Note
+from haiway import State, ctx
+from typing import Any
 
 # State providing contextual state for the functionality
 class NotesDirectory(State):
@@ -219,48 +174,59 @@ class NotesDirectory(State):
 # State encapsulating the functionality with its interface
 class Notes(State):
     # Call of note creation function
+    @classmethod
     async def create_note(cls, content: str, **extra: Any) -> Note:
         # Invoke the function implementation from the contextual state
-        await ctx.state(cls).create(content=content, **extra)
+        return await ctx.state(cls).creating(content=content, **extra)
 
     # Call of note update function
+    @classmethod
     async def update_note(cls, note: Note, **extra: Any) -> None:
         # Invoke the function implementation from the contextual state
-        await ctx.state(cls).update(note=note, **extra)
+        await ctx.state(cls).updating(note=note, **extra)
 
     # instance variables holding function implementations
     creating: NoteCreating
     updating: NoteUpdating
 ```
 
-That allows us to provide a concrete implementation. Note that `extra` arguments would allow us to alter the `NotesDirectory` path for a single function call only. This might be very important feature in some cases i.e. when using recursive function calls.
+That allows us to provide a concrete implementation. Note that `extra` arguments would allow us to alter the `NotesDirectory` path for a single function call only. This might be a very important feature in some cases, i.e., when using recursive function calls.
 
 ```python
 # notes/files.py
-from notes.types import FunctionArgument
+from notes.types import Note
 from notes.state import Notes, NotesDirectory
 from haiway import ctx
+from typing import Any
+from uuid import uuid4
+from datetime import datetime
 
 # Implementation of note creation function
 async def file_note_create(content: str, **extra: Any) -> Note:
     # Retrieve path from the current context's state, updated if needed
     path = ctx.state(NotesDirectory).updated(**extra).path
     # Store note in file within the path...
+    note = Note(
+        identifier=uuid4(),
+        last_update=datetime.now(),
+        content=content
+    )
+    # Implementation for storing note in file...
+    return note
 
 # Implementation of note update function
 async def file_note_update(note: Note, **extra: Any) -> None:
     # Retrieve path from the current context's state, updated if needed
     path = ctx.state(NotesDirectory).updated(**extra).path
     # Update the note...
-
+    # Implementation for updating note in file...
 
 # Factory function to instantiate the Notes utilizing files implementation
 def file_notes() -> Notes:
     return Notes(
-        create=file_note_create,
-        update=file_note_update,
+        creating=file_note_create,
+        updating=file_note_update,
     )
-
 ```
 
 You can now use the whole functionality by defining implementation for execution context and calling functionality methods.
@@ -273,5 +239,5 @@ from haiway import ctx
 # prepare the context with desired implementation
 async with ctx.scope("example", file_notes(), NotesDirectory(path="./examples/note.txt")):
     # and access its methods contextually
-    await Notes.create_note("This was an example of haiway")
+    await Notes.create_note("This was an example of Haiway")
 ```

haiway-0.21.1/guidelines/llms.txt

@@ -0,0 +1,259 @@
+## Package Structure
+
+Organize your project into five distinct package types:
+
+```
+src/
+├── commons/                # Shared utilities, types, extensions
+├── integrations/           # Third-party service connections
+│   ├── integration_a/
+│   └── integration_b/
+├── solutions/              # Low-level utilities
+│   ├── solution_a/
+│   └── solution_b/
+├── features/               # High-level functionalities
+│   ├── feature_a/
+│   └── feature_b/
+└── entrypoints/            # Application entry points
+    ├── entrypoint_a/
+    └── entrypoint_b/
+```
+
+Each functionality package should contain:
+- `__init__.py`: Exports public API only
+- `types.py`: Type definitions using Protocol and State
+- `state.py`: State declarations with classmethod helpers
+- `config.py`: Configuration constants
+
+## Implementing Types
+
+Define interfaces using Protocol and data using State:
+
+```python
+from typing import Protocol, Any, runtime_checkable
+from haiway import State
+
+# Data structure
+class UserData(State):
+    id: str
+    name: str
+    email: str | None = None
+
+# Function interface
+@runtime_checkable
+class UserFetching(Protocol):
+    async def __call__(self, id: str) -> UserData: ...
+```
+
+## State Management
+
+Define states for configuration and functionality containers:
+
+```python
+from haiway import State
+from .types import UserFetching, UserData
+
+# Configuration state
+class UserServiceConfig(State):
+    api_url: str = "https://api.example.com"
+    timeout_seconds: int = 30
+
+# Functionality container
+class UserService(State):
+    # Function implementations
+    fetching: UserFetching
+
+    # Class method interface
+    @classmethod
+    async def fetch_user(cls, id: str) -> UserData:
+        return await ctx.state(cls).fetching(id)
+```
+
+## Implementing Functions
+
+Create concrete implementations and factory methods:
+
+```python
+from haiway import ctx
+from .types import UserData
+from .state import UserService, UserServiceConfig
+
+# Concrete implementation
+async def http_user_fetching(id: str) -> UserData:
+    config = ctx.state(UserServiceConfig)
+    # Implementation using config.api_url
+    # ...
+    return UserData(id=id, name="Example User")
+
+# Factory function providing implementation
+def HTTPUserService() -> UserService:
+    return UserService(fetching=http_user_fetching)
+```
+
+## Using Context Scopes
+
+Establish context with state and implementations:
+
+```python
+from haiway import ctx
+from .state import UserService, UserServiceConfig
+from .implementation import HTTPUserService
+
+async def main():
+    # Set up execution context
+    async with ctx.scope(
+        "main",
+        HTTPUserService(),
+        UserServiceConfig(api_url="https://custom-api.example.com")
+    ):
+        # Use functionality through class methods
+        user = await UserService.fetch_user("user-123")
+        print(f"Found user: {user.name}")
+```
+
+## Managing State Updates
+
+Create state variants without mutation:
+
+```python
+# Current state
+config = ctx.state(UserServiceConfig)
+
+# Create new instance with updated values
+dev_config = config.updated(api_url="https://dev-api.example.com")
+
+# Use in context
+async with ctx.scope("dev-context", dev_config):
+    # Operations will use dev_config
+    pass
+```
+
+## Complete Example: Notes Manager
+
+```python
+from typing import Protocol, Any, runtime_checkable
+from uuid import UUID, uuid4
+from datetime import datetime
+from haiway import State, ctx
+
+# Types
+class Note(State):
+    id: UUID
+    content: str
+    created_at: datetime
+    updated_at: datetime
+
+@runtime_checkable
+class NoteCreating(Protocol):
+    async def __call__(self, content: str) -> Note: ...
+
+@runtime_checkable
+class NoteFinding(Protocol):
+    async def __call__(self, id: UUID) -> Note | None: ...
+
+# State
+class NotesConfig(State):
+    storage_path: str = "./notes"
+
+class NotesService(State):
+    creating: NoteCreating
+    finding: NoteFinding
+
+    @classmethod
+    async def create_note(cls, content: str) -> Note:
+        return await ctx.state(cls).creating(content)
+
+    @classmethod
+    async def find_note(cls, id: UUID) -> Note | None:
+        return await ctx.state(cls).finding(id)
+
+# Implementation
+async def file_note_creating(content: str) -> Note:
+    now = datetime.now()
+    note = Note(
+        id=uuid4(),
+        content=content,
+        created_at=now,
+        updated_at=now
+    )
+
+    config = ctx.state(NotesConfig)
+    # Save note to file at config.storage_path
+    # ...
+
+    return note
+
+async def file_note_finding(id: UUID) -> Note | None:
+    config = ctx.state(NotesConfig)
+    # Find note in files at config.storage_path
+    # ...
+
+    # Return found note or None
+    # For demonstration:
+    return Note(
+        id=id,
+        content="Example note content",
+        created_at=datetime.now(),
+        updated_at=datetime.now()
+    )
+
+# Factory
+def FileNotesService() -> NotesService:
+    return NotesService(
+        creating=file_note_creating,
+        finding=file_note_finding
+    )
+
+# Usage
+async def run_notes_app():
+    async with ctx.scope(
+        "notes-app",
+        FileNotesService(),
+        NotesConfig(storage_path="./my_notes")
+    ):
+        # Create a note
+        new_note = await NotesService.create_note("This is a test note")
+        print(f"Created note with ID: {new_note.id}")
+
+        # Find the note
+        found_note = await NotesService.find_note(new_note.id)
+        if found_note:
+            print(f"Found note: {found_note.content}")
+```
+
+## Best Practices
+
+1. **Type Definitions**
+   - Use Protocol for function interfaces
+   - Use State for data structures
+   - Apply runtime_checkable for better type safety
+
+2. **State Management**
+   - Keep states immutable
+   - Use .updated() for state variants
+   - Define defaults for optional values
+
+3. **Function Implementations**
+   - Access context through ctx.state()
+   - Keep functions pure when possible
+   - Return new objects instead of modifying existing ones
+
+4. **Class Method Interface**
+   - Define classmethods for cleaner API
+   - Use cls parameter to access current state
+   - Follow consistent naming (verb_noun pattern)
+
+5. **Context Usage**
+   - Use descriptive context names
+   - Group related states in single context
+   - Keep context hierarchy shallow
+
+6. **Package Organization**
+   - Separate interfaces from implementations
+   - Export only public API from __init__.py
+   - Group related functionality in dedicated packages
+
+7. **Error Handling**
+   - Define custom error types in types.py
+   - Handle errors explicitly at appropriate levels
+   - Maintain immutability in error cases