spryx-core 0.1.3

Core utilities and types for Spryx projects

Spryx Core

Core utilities and types for Spryx projects.

Overview

Spryx Core provides common utilities and type definitions used across Spryx projects, including:

• ID generation and validation using ULIDs
• Time manipulation and formatting utilities
• Pagination models for API responses
• Type definitions and sentinel values
• Common error classes
• Permission handling utilities

Installation

pip install spryx-core

For development or optional features:

# For ULID support (recommended for ID generation)
pip install "spryx-core[ulid]"

Documentation

The full documentation is available at https://spryx-ai.github.io/spryx-core-py/

Local Documentation

You can also build and view the documentation locally:

# Install documentation dependencies
pip install mkdocs-material "mkdocstrings[python]"

# Serve documentation locally
mkdocs serve

# Build documentation
mkdocs build

Quick Usage

from spryx_core import generate_entity_id, now_utc, to_iso, Page

# Generate unique IDs
entity_id = generate_entity_id()
print(entity_id)  # Example: 01HNJG7VWTZA0CGTJ9T7WG9CPB

# Work with UTC timestamps
current_time = now_utc()
iso_timestamp = to_iso(current_time)
print(iso_timestamp)  # Example: 2023-12-01T14:32:15.123456Z

# Create paginated responses
page = Page(
    items=["item1", "item2"],
    page=1,
    page_size=10,
    total=25
)
print(f"Current page: {page.page}, Total pages: {page.total_pages}")

Development

See the Contributing Guide for instructions on how to set up the development environment and contribute to the project.

License

MIT

Features

spryx-core provides common utilities and type definitions used across Spryx projects, including:

Entity IDs

• ULID generation and validation (with UUID fallback)
• Custom EntityId type

from spryx_core import EntityId, generate_entity_id, is_valid_ulid

# Generate a new ID
entity_id = generate_entity_id()

# Validate an ID
if is_valid_ulid(some_string):
    # ...

Time Utilities

• ISO-8601 UTC formatting and parsing
• Common time operations (start/end of day, etc.)

from spryx_core import now_utc, to_iso, parse_iso, start_of_day

# Get current UTC time
now = now_utc()

# Format as ISO string
iso_string = to_iso(now)

# Parse ISO string
dt = parse_iso("2023-04-01T12:00:00.000Z")

# Get start of day
day_start = start_of_day(now)

Sentinel Values

• NotGiven sentinel and related utilities
• NOT_GIVEN singleton instance

from spryx_core import NOT_GIVEN, NotGivenOr, is_given

def my_function(optional_param: NotGivenOr[str] = NOT_GIVEN):
    if is_given(optional_param):
        # Handle provided value
    else:
        # Handle not provided case

Enumerations

• Common enum types (Environment, SortOrder, etc.)

from spryx_core import Environment, SortOrder

# Environment types
if env == Environment.PRODUCTION:
    # ...

# Sort order
order = SortOrder.ASC

Documentation

Module: spryx_core.id

Functions for generating and validating entity IDs:

• generate_entity_id() -> EntityId: Generates a new ULID or UUID
• is_valid_ulid(value: str) -> bool: Validates a ULID string
• cast_entity_id(value: str) -> EntityId: Casts a string to an EntityId

Module: spryx_core.time

Date/time utilities with UTC focus:

• now_utc() -> datetime: Gets current UTC time
• to_iso(dt: datetime, milliseconds: bool = False) -> str: Formats as ISO-8601
• parse_iso(value: str) -> datetime: Parses ISO-8601 string
• utc_from_timestamp(ts: int | float) -> datetime: Converts timestamp to datetime
• start_of_day(dt: datetime | None = None) -> datetime: Gets day start (00:00:00)
• end_of_day(dt: datetime | None = None) -> datetime: Gets day end (23:59:59.999999)

Module: spryx_core.types

Type utilities:

• is_given(obj: NotGivenOr[_T]) -> TypeGuard[_T]: Checks if value is not NotGiven
• default_or_given(obj: NotGivenOr[_T], default: Any = None) -> Union[_T, None]: Gets value or default

Module: spryx_core.enums

Common enumerations:

• SortOrder: ASC, DESC
• Environment: DEV, STAGING, PRODUCTION

Module: spryx_core.sentinels

Sentinel values:

• NotGiven: Sentinel for unspecified values, distinct from None

Module: spryx_core.constants

Exported constants:

• NOT_GIVEN: Singleton instance of NotGiven

License

This project is licensed under the MIT License - see the LICENSE file for details.

Requirements

• Python 3.11+
• Dependencies:
  • python-ulid (>=3.0.0,<4.0.0)
  • pydantic (>=2.11.3,<3.0.0)