pierre-storage 0.1.3__tar.gz

pierre_storage-0.1.3/LICENSE

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

pierre_storage-0.1.3/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include pierre_storage *.py
+recursive-include pierre_storage py.typed

pierre_storage-0.1.3/PKG-INFO

@@ -0,0 +1,401 @@
+Metadata-Version: 2.4
+Name: pierre-storage
+Version: 0.1.3
+Summary: Pierre Git Storage SDK for Python
+Author-email: Pierre <support@pierre.io>
+License: MIT
+Project-URL: Homepage, https://pierre.io
+Project-URL: Documentation, https://docs.pierre.io
+Project-URL: Repository, https://github.com/pierre/monorepo
+Project-URL: Issues, https://github.com/pierre/monorepo/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyjwt>=2.8.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.5.0; python_version < "3.10"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# pierre-storage
+
+Pierre Git Storage SDK for Python applications.
+
+## Installation
+
+```bash
+pip install pierre-storage
+```
+
+## Usage
+
+### Basic Setup
+
+```python
+from pierre_storage import GitStorage
+
+# Initialize the client with your name and key
+storage = GitStorage({
+    "name": "your-name",  # e.g., 'v0'
+    "key": "your-key",  # Your API key in PEM format
+})
+```
+
+### Creating a Repository
+
+```python
+# Create a new repository with auto-generated ID
+repo = await storage.create_repo()
+print(repo.id)  # e.g., '123e4567-e89b-12d3-a456-426614174000'
+
+# Create a repository with custom ID
+custom_repo = await storage.create_repo({"id": "my-custom-repo"})
+print(custom_repo.id)  # 'my-custom-repo'
+```
+
+### Finding a Repository
+
+```python
+found_repo = await storage.find_one({"id": "repo-id"})
+if found_repo:
+    url = await found_repo.get_remote_url()
+    print(f"Repository URL: {url}")
+```
+
+### Getting Remote URLs
+
+The SDK generates secure URLs with JWT authentication for Git operations:
+
+```python
+# Get URL with default permissions (git:write, git:read) and 1-year TTL
+url = await repo.get_remote_url()
+# Returns: https://t:JWT@your-name.code.storage/repo-id.git
+
+# Configure the Git remote
+print(f"Run: git remote add origin {url}")
+
+# Get URL with custom permissions and TTL
+read_only_url = await repo.get_remote_url({
+    "permissions": ["git:read"],  # Read-only access
+    "ttl": 3600,  # 1 hour in seconds
+})
+
+# Available permissions:
+# - 'git:read'   - Read access to Git repository
+# - 'git:write'  - Write access to Git repository
+# - 'repo:write' - Create a repository
+```
+
+### Working with Repository Content
+
+Once you have a repository instance, you can perform various Git operations:
+
+```python
+repo = await storage.create_repo()
+# or
+repo = await storage.find_one({"id": "existing-repo-id"})
+
+# Get file content (streaming)
+response = await repo.get_file_stream({
+    "path": "README.md",
+    "ref": "main",  # optional, defaults to default branch
+})
+text = await response.aread()
+print(text.decode())
+
+# List all files in the repository
+files = await repo.list_files({
+    "ref": "main",  # optional, defaults to default branch
+})
+print(files["paths"])  # List of file paths
+
+# List branches
+branches = await repo.list_branches({
+    "limit": 10,
+    "cursor": None,  # for pagination
+})
+print(branches["branches"])
+
+# List commits
+commits = await repo.list_commits({
+    "branch": "main",  # optional
+    "limit": 20,
+    "cursor": None,  # for pagination
+})
+print(commits["commits"])
+
+# Get branch diff
+branch_diff = await repo.get_branch_diff({
+    "branch": "feature-branch",
+    "base": "main",  # optional, defaults to main
+})
+print(branch_diff["stats"])
+print(branch_diff["files"])
+
+# Get commit diff
+commit_diff = await repo.get_commit_diff({
+    "sha": "abc123...",
+})
+print(commit_diff["stats"])
+print(commit_diff["files"])
+```
+
+### Creating Commits
+
+The SDK provides a fluent builder API for creating commits with streaming support:
+
+```python
+# Create a commit
+result = await (
+    repo.create_commit({
+        "target_branch": "main",
+        "commit_message": "Update docs",
+        "author": {"name": "Docs Bot", "email": "docs@example.com"},
+    })
+    .add_file_from_string("docs/changelog.md", "# v2.0.1\n- add streaming SDK\n")
+    .add_file("docs/readme.md", b"Binary content here")
+    .delete_path("docs/legacy.txt")
+    .send()
+)
+
+print(result["commit_sha"])
+print(result["ref_update"]["new_sha"])
+print(result["ref_update"]["old_sha"])  # All zeroes when ref is created
+```
+
+The builder exposes:
+
+- `add_file(path, source, options)` - Attach bytes from various sources
+- `add_file_from_string(path, contents, encoding, options)` - Add text files (defaults to UTF-8)
+- `delete_path(path)` - Remove files or folders
+- `send()` - Finalize the commit and receive metadata
+
+`send()` returns a result with:
+
+```python
+{
+    "commit_sha": str,
+    "tree_sha": str,
+    "target_branch": str,
+    "pack_bytes": int,
+    "blob_count": int,
+    "ref_update": {
+        "branch": str,
+        "old_sha": str,  # All zeroes when the ref is created
+        "new_sha": str,
+    }
+}
+```
+
+If the backend reports a failure, the builder raises a `RefUpdateError` containing the status, reason, and ref details.
+
+**Options:**
+
+- `target_branch` (required): Branch name (without `refs/heads/` prefix)
+- `expected_head_sha` (optional): Branch or commit that must match the remote tip
+- `commit_message` (required): The commit message
+- `author` (required): Dictionary with `name` and `email`
+- `committer` (optional): Dictionary with `name` and `email` (defaults to author)
+
+> Files are chunked into 4 MiB segments, allowing streaming of large assets without buffering in memory.
+
+> The `target_branch` must already exist on the remote repository. To seed an empty repository, omit `expected_head_sha`; the service will create the first commit only when no refs are present.
+
+### Streaming Large Files
+
+The commit builder accepts async iterables, allowing streaming of large files:
+
+```python
+async def file_chunks():
+    """Generate file chunks asynchronously."""
+    with open("/tmp/large-file.zip", "rb") as f:
+        while chunk := f.read(1024 * 1024):  # Read 1MB at a time
+            yield chunk
+
+result = await (
+    repo.create_commit({
+        "target_branch": "assets",
+        "expected_head_sha": "abc123...",
+        "commit_message": "Upload latest design bundle",
+        "author": {"name": "Assets Uploader", "email": "assets@example.com"},
+    })
+    .add_file("assets/design-kit.zip", file_chunks())
+    .send()
+)
+```
+
+### Restoring Commits
+
+You can restore a repository to a previous commit:
+
+```python
+result = await repo.restore_commit({
+    "target_branch": "main",
+    "target_commit_sha": "abc123...",  # Commit to restore to
+    "expected_head_sha": "def456...",  # Optional: current HEAD for safety
+    "commit_message": "Restore to stable version",
+    "author": {"name": "DevOps", "email": "devops@example.com"},
+})
+
+print(result["commit_sha"])
+print(result["ref_update"])
+```
+
+## API Reference
+
+### GitStorage
+
+```python
+class GitStorage:
+    def __init__(self, options: GitStorageOptions) -> None: ...
+    async def create_repo(self, options: CreateRepoOptions = None) -> Repo: ...
+    async def find_one(self, options: FindOneOptions) -> Optional[Repo]: ...
+    def get_config(self) -> GitStorageOptions: ...
+```
+
+### Repo
+
+```python
+class Repo:
+    @property
+    def id(self) -> str: ...
+
+    async def get_remote_url(self, options: GetRemoteURLOptions = None) -> str: ...
+    async def get_file_stream(self, options: GetFileOptions) -> Response: ...
+    async def list_files(self, options: ListFilesOptions = None) -> ListFilesResult: ...
+    async def list_branches(self, options: ListBranchesOptions = None) -> ListBranchesResult: ...
+    async def list_commits(self, options: ListCommitsOptions = None) -> ListCommitsResult: ...
+    async def get_branch_diff(self, options: GetBranchDiffOptions) -> GetBranchDiffResult: ...
+    async def get_commit_diff(self, options: GetCommitDiffOptions) -> GetCommitDiffResult: ...
+    async def pull_upstream(self, options: PullUpstreamOptions = None) -> None: ...
+    async def restore_commit(self, options: RestoreCommitOptions) -> RestoreCommitResult: ...
+    def create_commit(self, options: CreateCommitOptions) -> CommitBuilder: ...
+```
+
+### Type Definitions
+
+All types are provided via TypedDict for better IDE support:
+
+```python
+from pierre_storage.types import (
+    GitStorageOptions,
+    CreateRepoOptions,
+    GetRemoteURLOptions,
+    CommitSignature,
+    # ... and more
+)
+```
+
+## Webhook Validation
+
+The SDK includes utilities for validating webhook signatures:
+
+```python
+from pierre_storage import validate_webhook, parse_push_event
+
+# Validate webhook signature
+result = validate_webhook(
+    payload=request.body.decode(),  # Raw payload string
+    signature=request.headers["X-Pierre-Signature"],
+    secret="your-webhook-secret",
+    options={"max_age_seconds": 300},  # 5 minutes
+)
+
+if result["valid"]:
+    # Parse the event
+    data = json.loads(request.body)
+
+    if result["event_type"] == "push":
+        event = parse_push_event(data)
+        print(f"Push to {event['ref']}")
+        print(f"Commit: {event['before']} -> {event['after']}")
+else:
+    print(f"Invalid webhook: {result['error']}")
+```
+
+## Authentication
+
+The SDK uses JWT (JSON Web Tokens) for authentication. When you call `get_remote_url()`, it:
+
+1. Creates a JWT with your name, repository ID, and requested permissions
+2. Signs it with your private key (ES256, RS256, or EdDSA)
+3. Embeds it in the Git remote URL as the password
+
+The generated URLs are compatible with standard Git clients and include all necessary authentication.
+
+## Error Handling
+
+The SDK provides specific error classes:
+
+```python
+from pierre_storage import ApiError, RefUpdateError
+
+try:
+    repo = await storage.create_repo({"id": "existing"})
+except ApiError as e:
+    print(f"API error: {e.message}")
+    print(f"Status code: {e.status_code}")
+
+try:
+    result = await builder.send()
+except RefUpdateError as e:
+    print(f"Ref update failed: {e.message}")
+    print(f"Status: {e.status}")
+    print(f"Reason: {e.reason}")
+    print(f"Ref update: {e.ref_update}")
+```
+
+## Development
+
+### Setup
+
+```bash
+# Create virtual environment and install dependencies
+python3 -m venv venv
+source venv/bin/activate
+pip install -e ".[dev]"
+
+# Or use Moon
+moon run git-storage-sdk-python:setup
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=pierre_storage --cov-report=html
+
+# Type checking
+mypy pierre_storage
+
+# Linting
+ruff check pierre_storage
+```
+
+### Building
+
+```bash
+python -m build
+```
+
+## License
+
+MIT