timeback-oneroster 0.1.0__tar.gz

timeback_oneroster-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# uv
+uv.lock
+
+# ruff
+.ruff_cache/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

timeback_oneroster-0.1.0/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: timeback-oneroster
+Version: 0.1.0
+Summary: Timeback OneRoster v1.2 client for rostering and gradebook APIs
+Author-email: Timeback <dev@timeback.dev>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: timeback-common>=0.1.0
+Description-Content-Type: text/markdown
+
+# timeback-oneroster
+
+Python client for the OneRoster v1.2 API.
+
+## Installation
+
+```bash
+pip install timeback-oneroster
+```
+
+## Quick Start
+
+```python
+from timeback_oneroster import OneRosterClient
+
+async def main():
+    client = OneRosterClient(
+        env="staging",  # or "production"
+        client_id="your-client-id",
+        client_secret="your-client-secret",
+    )
+
+    # List all schools
+    schools = await client.schools.list()
+    for school in schools:
+        print(school.name)
+
+    # Get a specific user
+    user = await client.users.get("user-sourced-id")
+    print(f"{user.given_name} {user.family_name}")
+
+    await client.close()
+```
+
+## Client Structure
+
+```python
+client = OneRosterClient(options)
+
+# Rostering
+client.users        # All users
+client.students     # Students (filtered users)
+client.teachers     # Teachers (filtered users)
+client.classes      # Classes
+client.schools      # Schools
+# client.courses    # Coming soon
+# client.enrollments # Coming soon
+# client.terms      # Coming soon
+```
+
+## Resource Operations
+
+Each resource supports:
+
+```python
+# List all items
+users = await client.users.list()
+
+# List with type-safe filtering (recommended)
+active_teachers = await client.users.list(
+    where={"status": "active", "role": "teacher"}
+)
+
+# With operators
+teachers_or_aides = await client.users.list(
+    where={"role": {"in_": ["teacher", "aide"]}}
+)
+
+# Not equal
+non_deleted = await client.users.list(
+    where={"status": {"ne": "deleted"}}
+)
+
+# Sorting
+sorted_users = await client.users.list(
+    where={"status": "active"},
+    sort="familyName",
+    order_by="asc",
+)
+
+# Legacy filter string (still supported)
+active_users = await client.users.list(filter="status='active'")
+
+# Get by sourcedId
+user = await client.users.get("user-id")
+
+# Create (where supported)
+await client.classes.create({
+    "title": "Math 101",
+    "course": {"sourcedId": "course-id"},
+    "school": {"sourcedId": "school-id"},
+})
+
+# Update (where supported)
+await client.classes.update("class-id", {"title": "Math 102"})
+
+# Delete (where supported)
+await client.classes.delete("class-id")
+```
+
+## Nested Resources
+
+```python
+# Schools
+classes = await client.schools("school-id").classes()
+students = await client.schools("school-id").students()
+teachers = await client.schools("school-id").teachers()
+courses = await client.schools("school-id").courses()
+
+# Classes
+students = await client.classes("class-id").students()
+teachers = await client.classes("class-id").teachers()
+enrollments = await client.classes("class-id").enrollments()
+
+# Enroll a student
+await client.classes("class-id").enroll("student-id", role="student")
+
+# Users
+classes = await client.users("user-id").classes()
+demographics = await client.users("user-id").demographics()
+
+# Students / Teachers
+classes = await client.students("student-id").classes()
+classes = await client.teachers("teacher-id").classes()
+```
+
+## Filtering
+
+The client supports type-safe filtering with the `where` parameter:
+
+```python
+# Simple equality
+users = await client.users.list(where={"status": "active"})
+
+# Multiple conditions (AND)
+users = await client.users.list(
+    where={"status": "active", "role": "teacher"}
+)
+
+# Operators
+users = await client.users.list(where={"score": {"gte": 90}})        # >=
+users = await client.users.list(where={"score": {"gt": 90}})         # >
+users = await client.users.list(where={"score": {"lte": 90}})        # <=
+users = await client.users.list(where={"score": {"lt": 90}})         # <
+users = await client.users.list(where={"status": {"ne": "deleted"}}) # !=
+users = await client.users.list(where={"email": {"contains": "@school.edu"}})  # substring
+
+# Match any of multiple values (OR)
+users = await client.users.list(
+    where={"role": {"in_": ["teacher", "aide"]}}
+)
+
+# Exclude multiple values
+users = await client.users.list(
+    where={"status": {"not_in": ["deleted", "inactive"]}}
+)
+
+# Explicit OR across fields
+users = await client.users.list(
+    where={"OR": [{"role": "teacher"}, {"status": "active"}]}
+)
+```
+
+## Pagination
+
+For large datasets, use streaming:
+
+```python
+# Collect all users
+all_users = await client.users.stream().to_list()
+
+# With limits
+first_100 = await client.users.stream(max_items=100).to_list()
+
+# With filtering
+active_users = await client.users.stream(
+    where={"status": "active"}
+).to_list()
+
+# Get first item only
+first_user = await client.users.stream().first()
+```
+
+## Configuration
+
+```python
+OneRosterClient(
+    # Environment-based (recommended)
+    env="production",  # or "staging"
+    client_id="...",
+    client_secret="...",
+
+    # Or explicit URLs
+    base_url="https://api.example.com",
+    auth_url="https://auth.example.com/oauth2/token",
+    client_id="...",
+    client_secret="...",
+
+    # Optional
+    timeout=30.0,  # Request timeout in seconds
+)
+```
+
+## Environment Variables
+
+If credentials are not provided explicitly, the client reads from:
+
+- `ONEROSTER_CLIENT_ID`
+- `ONEROSTER_CLIENT_SECRET`
+- `ONEROSTER_BASE_URL` (optional)
+- `ONEROSTER_TOKEN_URL` (optional)
+
+## Error Handling
+
+```python
+from timeback_oneroster import OneRosterError, NotFoundError, AuthenticationError
+
+try:
+    user = await client.users.get("invalid-id")
+except NotFoundError as e:
+    print(f"User not found: {e.sourced_id}")
+except AuthenticationError:
+    print("Invalid credentials")
+except OneRosterError as e:
+    print(f"API error: {e}")
+```
+
+## Async Context Manager
+
+```python
+async with OneRosterClient(client_id="...", client_secret="...") as client:
+    schools = await client.schools.list()
+# Client is automatically closed
+```
+
+## FastAPI Integration
+
+```python
+from fastapi import FastAPI, Depends
+from timeback_oneroster import OneRosterClient
+
+app = FastAPI()
+
+async def get_oneroster():
+    client = OneRosterClient(
+        env="production",
+        client_id="...",
+        client_secret="...",
+    )
+    try:
+        yield client
+    finally:
+        await client.close()
+
+@app.get("/schools")
+async def list_schools(client: OneRosterClient = Depends(get_oneroster)):
+    return await client.schools.list()
+```

timeback_oneroster-0.1.0/README.md

@@ -0,0 +1,258 @@
+# timeback-oneroster
+
+Python client for the OneRoster v1.2 API.
+
+## Installation
+
+```bash
+pip install timeback-oneroster
+```
+
+## Quick Start
+
+```python
+from timeback_oneroster import OneRosterClient
+
+async def main():
+    client = OneRosterClient(
+        env="staging",  # or "production"
+        client_id="your-client-id",
+        client_secret="your-client-secret",
+    )
+
+    # List all schools
+    schools = await client.schools.list()
+    for school in schools:
+        print(school.name)
+
+    # Get a specific user
+    user = await client.users.get("user-sourced-id")
+    print(f"{user.given_name} {user.family_name}")
+
+    await client.close()
+```
+
+## Client Structure
+
+```python
+client = OneRosterClient(options)
+
+# Rostering
+client.users        # All users
+client.students     # Students (filtered users)
+client.teachers     # Teachers (filtered users)
+client.classes      # Classes
+client.schools      # Schools
+# client.courses    # Coming soon
+# client.enrollments # Coming soon
+# client.terms      # Coming soon
+```
+
+## Resource Operations
+
+Each resource supports:
+
+```python
+# List all items
+users = await client.users.list()
+
+# List with type-safe filtering (recommended)
+active_teachers = await client.users.list(
+    where={"status": "active", "role": "teacher"}
+)
+
+# With operators
+teachers_or_aides = await client.users.list(
+    where={"role": {"in_": ["teacher", "aide"]}}
+)
+
+# Not equal
+non_deleted = await client.users.list(
+    where={"status": {"ne": "deleted"}}
+)
+
+# Sorting
+sorted_users = await client.users.list(
+    where={"status": "active"},
+    sort="familyName",
+    order_by="asc",
+)
+
+# Legacy filter string (still supported)
+active_users = await client.users.list(filter="status='active'")
+
+# Get by sourcedId
+user = await client.users.get("user-id")
+
+# Create (where supported)
+await client.classes.create({
+    "title": "Math 101",
+    "course": {"sourcedId": "course-id"},
+    "school": {"sourcedId": "school-id"},
+})
+
+# Update (where supported)
+await client.classes.update("class-id", {"title": "Math 102"})
+
+# Delete (where supported)
+await client.classes.delete("class-id")
+```
+
+## Nested Resources
+
+```python
+# Schools
+classes = await client.schools("school-id").classes()
+students = await client.schools("school-id").students()
+teachers = await client.schools("school-id").teachers()
+courses = await client.schools("school-id").courses()
+
+# Classes
+students = await client.classes("class-id").students()
+teachers = await client.classes("class-id").teachers()
+enrollments = await client.classes("class-id").enrollments()
+
+# Enroll a student
+await client.classes("class-id").enroll("student-id", role="student")
+
+# Users
+classes = await client.users("user-id").classes()
+demographics = await client.users("user-id").demographics()
+
+# Students / Teachers
+classes = await client.students("student-id").classes()
+classes = await client.teachers("teacher-id").classes()
+```
+
+## Filtering
+
+The client supports type-safe filtering with the `where` parameter:
+
+```python
+# Simple equality
+users = await client.users.list(where={"status": "active"})
+
+# Multiple conditions (AND)
+users = await client.users.list(
+    where={"status": "active", "role": "teacher"}
+)
+
+# Operators
+users = await client.users.list(where={"score": {"gte": 90}})        # >=
+users = await client.users.list(where={"score": {"gt": 90}})         # >
+users = await client.users.list(where={"score": {"lte": 90}})        # <=
+users = await client.users.list(where={"score": {"lt": 90}})         # <
+users = await client.users.list(where={"status": {"ne": "deleted"}}) # !=
+users = await client.users.list(where={"email": {"contains": "@school.edu"}})  # substring
+
+# Match any of multiple values (OR)
+users = await client.users.list(
+    where={"role": {"in_": ["teacher", "aide"]}}
+)
+
+# Exclude multiple values
+users = await client.users.list(
+    where={"status": {"not_in": ["deleted", "inactive"]}}
+)
+
+# Explicit OR across fields
+users = await client.users.list(
+    where={"OR": [{"role": "teacher"}, {"status": "active"}]}
+)
+```
+
+## Pagination
+
+For large datasets, use streaming:
+
+```python
+# Collect all users
+all_users = await client.users.stream().to_list()
+
+# With limits
+first_100 = await client.users.stream(max_items=100).to_list()
+
+# With filtering
+active_users = await client.users.stream(
+    where={"status": "active"}
+).to_list()
+
+# Get first item only
+first_user = await client.users.stream().first()
+```
+
+## Configuration
+
+```python
+OneRosterClient(
+    # Environment-based (recommended)
+    env="production",  # or "staging"
+    client_id="...",
+    client_secret="...",
+
+    # Or explicit URLs
+    base_url="https://api.example.com",
+    auth_url="https://auth.example.com/oauth2/token",
+    client_id="...",
+    client_secret="...",
+
+    # Optional
+    timeout=30.0,  # Request timeout in seconds
+)
+```
+
+## Environment Variables
+
+If credentials are not provided explicitly, the client reads from:
+
+- `ONEROSTER_CLIENT_ID`
+- `ONEROSTER_CLIENT_SECRET`
+- `ONEROSTER_BASE_URL` (optional)
+- `ONEROSTER_TOKEN_URL` (optional)
+
+## Error Handling
+
+```python
+from timeback_oneroster import OneRosterError, NotFoundError, AuthenticationError
+
+try:
+    user = await client.users.get("invalid-id")
+except NotFoundError as e:
+    print(f"User not found: {e.sourced_id}")
+except AuthenticationError:
+    print("Invalid credentials")
+except OneRosterError as e:
+    print(f"API error: {e}")
+```
+
+## Async Context Manager
+
+```python
+async with OneRosterClient(client_id="...", client_secret="...") as client:
+    schools = await client.schools.list()
+# Client is automatically closed
+```
+
+## FastAPI Integration
+
+```python
+from fastapi import FastAPI, Depends
+from timeback_oneroster import OneRosterClient
+
+app = FastAPI()
+
+async def get_oneroster():
+    client = OneRosterClient(
+        env="production",
+        client_id="...",
+        client_secret="...",
+    )
+    try:
+        yield client
+    finally:
+        await client.close()
+
+@app.get("/schools")
+async def list_schools(client: OneRosterClient = Depends(get_oneroster)):
+    return await client.schools.list()
+```

timeback_oneroster-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "timeback-oneroster"
+version = "0.1.0"
+description = "Timeback OneRoster v1.2 client for rostering and gradebook APIs"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "Timeback", email = "dev@timeback.dev" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "timeback-common>=0.1.0",
+]
+
+[tool.uv.sources]
+timeback-common = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/timeback_oneroster"]

timeback_oneroster-0.1.0/pytest.ini

@@ -0,0 +1,5 @@
+[pytest]
+asyncio_mode = auto
+testpaths = tests
+python_files = test_*.py
+python_functions = test_*