unitysvc-services 0.1.0__tar.gz

unitysvc_services-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,296 @@
+# Contributing
+
+Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
+
+## Types of Contributions
+
+### Report Bugs
+
+Report bugs at https://github.com/unitysvc/unitysvc-services/issues.
+
+If you are reporting a bug, please include:
+
+- Your operating system name and version
+- Python version
+- Any details about your local setup that might be helpful in troubleshooting
+- Detailed steps to reproduce the bug
+
+### Fix Bugs
+
+Look through the GitHub issues for bugs. Anything tagged with "bug" and "help wanted" is open to whoever wants to implement it.
+
+### Implement Features
+
+Look through the GitHub issues for features. Anything tagged with "enhancement" and "help wanted" is open to whoever wants to implement it.
+
+### Write Documentation
+
+UnitySVC Provider SDK can always use more documentation, whether as part of the official docs, in docstrings, or even on the web in blog posts, articles, and such.
+
+### Submit Feedback
+
+The best way to send feedback is to file an issue at https://github.com/unitysvc/unitysvc-services/issues.
+
+If you are proposing a feature:
+
+- Explain in detail how it would work
+- Keep the scope as narrow as possible, to make it easier to implement
+- Remember that this is a volunteer-driven project, and that contributions are welcome :)
+
+## Getting Started
+
+Ready to contribute? Here's how to set up `unitysvc-services` for local development.
+
+### 1. Fork and Clone
+
+Fork the repo on GitHub, then clone your fork locally:
+
+```bash
+git clone git@github.com:your_username/unitysvc-services.git
+cd unitysvc-services
+```
+
+### 2. Set Up Development Environment
+
+Using uv (recommended):
+
+```bash
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Create virtual environment and install dependencies
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install -e ".[dev]"
+```
+
+Using pip:
+
+```bash
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+```
+
+### 3. Create a Branch
+
+```bash
+git checkout -b feature/my-feature
+# or
+git checkout -b fix/my-bugfix
+```
+
+### 4. Make Your Changes
+
+- Write clear, documented code
+- Add tests for new functionality
+- Update documentation as needed
+
+### 5. Run Tests and Linting
+
+```bash
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=unitysvc_services --cov-report=html
+
+# Lint code
+ruff check .
+ruff format .
+
+# Type checking
+mypy src/
+```
+
+### 6. Commit and Push
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```bash
+git add .
+git commit -m "feat: Add new feature"
+# or
+git commit -m "fix: Fix bug in validation"
+git push origin feature/my-feature
+```
+
+Commit types:
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation changes
+- `refactor:` Code refactoring
+- `test:` Test changes
+- `chore:` Maintenance tasks
+
+### 7. Submit a Pull Request
+
+Submit a pull request through GitHub.
+
+## Pull Request Guidelines
+
+Before you submit a pull request, check that it meets these guidelines:
+
+1. **Tests**: The pull request should include tests for new functionality
+2. **Documentation**: Update docs if adding/changing features
+3. **Code Quality**: All linting checks must pass
+4. **Python Versions**: Code should work with Python 3.11+
+5. **Type Hints**: Include type hints for all functions
+6. **Docstrings**: Use Google-style docstrings
+
+## Development Guidelines
+
+### Code Style
+
+- Follow PEP 8
+- Use type hints
+- Write descriptive docstrings
+- Keep functions focused and small
+- Use meaningful variable names
+
+Example:
+
+```python
+from pathlib import Path
+from typing import Optional
+
+def find_service(
+    name: str,
+    data_dir: Path,
+    *,
+    strict: bool = False
+) -> Optional[dict[str, Any]]:
+    """
+    Find a service by name.
+
+    Args:
+        name: Service name to search for
+        data_dir: Directory to search in
+        strict: Whether to enforce strict matching
+
+    Returns:
+        Service data dictionary or None if not found
+
+    Raises:
+        ValueError: If name is invalid
+    """
+    # Implementation
+    pass
+```
+
+### Testing
+
+- Write unit tests for all new functions
+- Use `tmp_path` fixture for file operations
+- Test both success and error cases
+- Aim for high code coverage
+
+Example:
+
+```python
+def test_load_json_file(tmp_path: Path):
+    """Test loading JSON file."""
+    # Arrange
+    test_file = tmp_path / "test.json"
+    test_file.write_text('{"schema": "provider_v1"}')
+
+    # Act
+    data, fmt = load_data_file(test_file)
+
+    # Assert
+    assert fmt == "json"
+    assert data["schema"] == "provider_v1"
+```
+
+### Documentation
+
+- Update relevant documentation in `docs/`
+- Add examples for new features
+- Keep README.md up to date
+- Use clear, concise language
+
+## Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test file
+pytest tests/test_utils.py
+
+# Run specific test
+pytest tests/test_utils.py::test_load_json_file
+
+# Run with verbose output
+pytest -v
+
+# Run with coverage
+pytest --cov=unitysvc_services --cov-report=html
+open htmlcov/index.html
+```
+
+## Building Documentation
+
+```bash
+# Install MkDocs
+pip install mkdocs mkdocs-material
+
+# Serve locally
+mkdocs serve
+
+# Build static site
+mkdocs build
+```
+
+## Release Process (Maintainers Only)
+
+### 1. Update Version
+
+Update version in `pyproject.toml`:
+
+```toml
+[project]
+version = "0.2.0"
+```
+
+### 2. Update Changelog
+
+Update `CHANGELOG.md` with release notes.
+
+### 3. Create Tag
+
+```bash
+git tag -a v0.2.0 -m "Release 0.2.0"
+git push origin v0.2.0
+```
+
+### 4. Build and Publish
+
+```bash
+# Build package
+python -m build
+
+# Upload to PyPI
+python -m twine upload dist/*
+```
+
+### 5. Deploy Documentation
+
+```bash
+mkdocs gh-deploy
+```
+
+## Code of Conduct
+
+Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
+
+## Questions?
+
+- Check the [Development Guide](docs/development.md) for detailed information
+- Look through existing [issues](https://github.com/unitysvc/unitysvc-services/issues)
+- Open a new issue if you need help
+
+Thank you for contributing!

unitysvc_services-0.1.0/HISTORY.md

@@ -0,0 +1,5 @@
+# History
+
+## 0.1.0 (2025-10-03)
+
+* First release on PyPI.

unitysvc_services-0.1.0/LICENSE

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

unitysvc_services-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include CONTRIBUTING.md
+include HISTORY.md
+include LICENSE
+include README.md
+
+recursive-include tests *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+
+recursive-include docs *.md Makefile *.jpg *.png *.gif

unitysvc_services-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: unitysvc-services
+Version: 0.1.0
+Summary: SDK for digital service providers on UnitySVC
+Author-email: Bo Peng <bo.peng@unitysvc.com>
+Maintainer-email: Bo Peng <bo.peng@unitysvc.com>
+License: MIT
+Project-URL: bugs, https://github.com/unitysvc/unitysvc-services/issues
+Project-URL: changelog, https://github.com/unitysvc/unitysvc-services/blob/master/changelog.md
+Project-URL: homepage, https://github.com/unitysvc/unitysvc-services
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer
+Requires-Dist: pydantic
+Requires-Dist: jsonschema
+Requires-Dist: jinja2
+Requires-Dist: rich
+Requires-Dist: httpx
+Requires-Dist: tomli-w
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: ruff; extra == "test"
+Requires-Dist: mypy; extra == "test"
+Requires-Dist: ipdb; extra == "test"
+Provides-Extra: dev
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: ty; extra == "dev"
+Requires-Dist: ipdb; extra == "dev"
+Requires-Dist: mkdocs; extra == "dev"
+Requires-Dist: mkdocs-material; extra == "dev"
+Requires-Dist: mkdocs-autorefs; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocs-autorefs; extra == "docs"
+Dynamic: license-file
+
+# UnitySVC Provider SDK
+
+![PyPI version](https://img.shields.io/pypi/v/unitysvc-services.svg)
+[![Documentation Status](https://readthedocs.org/projects/unitysvc-services/badge/?version=latest)](https://unitysvc-services.readthedocs.io/en/latest/?version=latest)
+
+Client library and CLI tools for digital service providers to interact with the UnitySVC platform.
+
+**📚 [Full Documentation](https://unitysvc-services.readthedocs.io)** | **🚀 [Getting Started](https://unitysvc-services.readthedocs.io/en/latest/getting-started/)** | **📖 [CLI Reference](https://unitysvc-services.readthedocs.io/en/latest/cli-reference/)**
+
+## Overview
+
+UnitySVC Provider SDK enables digital service providers to manage their service offerings through a **local-first, version-controlled workflow**:
+
+- **Define** service data using schema-validated files (JSON/TOML)
+- **Manage** everything locally in git-controlled directories
+- **Validate** data against schemas before publishing
+- **Publish** to UnitySVC platform when ready
+- **Automate** with populate scripts for dynamic catalogs
+
+## Installation
+
+```bash
+pip install unitysvc-services
+```
+
+Requires Python 3.11+
+
+## Quick Example
+
+```bash
+# Initialize provider and service
+unitysvc_services init provider my-provider
+unitysvc_services init offering my-service
+unitysvc_services init seller my-marketplace
+
+# Validate and format
+unitysvc_services validate
+unitysvc_services format
+
+# Publish to platform
+export UNITYSVC_BACKEND_URL="https://api.unitysvc.com/api/v1"
+export UNITYSVC_API_KEY="your-api-key"
+
+unitysvc_services publish providers
+unitysvc_services publish sellers
+unitysvc_services publish offerings
+unitysvc_services publish listings
+
+# Verify
+unitysvc_services query offerings
+```
+
+## Key Features
+
+- 📋 **Pydantic Models** - Type-safe data models for all entities
+- ✅ **Data Validation** - Comprehensive schema validation
+- 🔄 **Local-First** - Work offline, commit to git, publish when ready
+- 🚀 **CLI Tools** - Complete command-line interface
+- 🤖 **Automation** - Script-based service generation
+- 📝 **Multiple Formats** - Support for JSON and TOML
+
+## Workflows
+
+### Manual Workflow (small catalogs)
+
+```bash
+init → edit files → validate → format → publish → verify
+```
+
+### Automated Workflow (large/dynamic catalogs)
+
+```bash
+init provider → configure populate script → populate → validate → publish
+```
+
+See [Workflows Documentation](https://unitysvc-services.readthedocs.io/en/latest/workflows/) for details.
+
+## Data Structure
+
+```
+data/
+├── seller.json                    # One seller per repo
+├── ${provider_name}/
+│   ├── provider.json              # Provider metadata
+│   ├── docs/                      # Shared documentation
+│   └── services/
+│       └── ${service_name}/
+│           ├── service.json       # Service offering
+│           └── listing-*.json     # Service listing(s)
+```
+
+See [Data Structure Documentation](https://unitysvc-services.readthedocs.io/en/latest/data-structure/) for complete details.
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `init` | Initialize new data files from schemas |
+| `list` | List local data files |
+| `query` | Query backend API for published data |
+| `publish` | Publish data to backend |
+| `update` | Update local file fields |
+| `validate` | Validate data consistency |
+| `format` | Format data files |
+| `populate` | Execute provider populate scripts |
+
+Run `unitysvc_services --help` or see [CLI Reference](https://unitysvc-services.readthedocs.io/en/latest/cli-reference/) for complete documentation.
+
+## Documentation
+
+- **[Getting Started](https://unitysvc-services.readthedocs.io/en/latest/getting-started/)** - Installation and first steps
+- **[Data Structure](https://unitysvc-services.readthedocs.io/en/latest/data-structure/)** - File organization rules
+- **[Workflows](https://unitysvc-services.readthedocs.io/en/latest/workflows/)** - Manual and automated patterns
+- **[CLI Reference](https://unitysvc-services.readthedocs.io/en/latest/cli-reference/)** - All commands and options
+- **[File Schemas](https://unitysvc-services.readthedocs.io/en/latest/file-schemas/)** - Schema specifications
+- **[Python API](https://unitysvc-services.readthedocs.io/en/latest/api-reference/)** - Programmatic usage
+
+## Links
+
+- **PyPI**: https://pypi.org/project/unitysvc-services/
+- **Documentation**: https://unitysvc-services.readthedocs.io
+- **Source Code**: https://github.com/unitysvc/unitysvc-services
+- **Issue Tracker**: https://github.com/unitysvc/unitysvc-services/issues
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions welcome! See [Contributing Guide](https://unitysvc-services.readthedocs.io/en/latest/contributing/) for details.

unitysvc_services-0.1.0/README.md

@@ -0,0 +1,131 @@
+# UnitySVC Provider SDK
+
+![PyPI version](https://img.shields.io/pypi/v/unitysvc-services.svg)
+[![Documentation Status](https://readthedocs.org/projects/unitysvc-services/badge/?version=latest)](https://unitysvc-services.readthedocs.io/en/latest/?version=latest)
+
+Client library and CLI tools for digital service providers to interact with the UnitySVC platform.
+
+**📚 [Full Documentation](https://unitysvc-services.readthedocs.io)** | **🚀 [Getting Started](https://unitysvc-services.readthedocs.io/en/latest/getting-started/)** | **📖 [CLI Reference](https://unitysvc-services.readthedocs.io/en/latest/cli-reference/)**
+
+## Overview
+
+UnitySVC Provider SDK enables digital service providers to manage their service offerings through a **local-first, version-controlled workflow**:
+
+- **Define** service data using schema-validated files (JSON/TOML)
+- **Manage** everything locally in git-controlled directories
+- **Validate** data against schemas before publishing
+- **Publish** to UnitySVC platform when ready
+- **Automate** with populate scripts for dynamic catalogs
+
+## Installation
+
+```bash
+pip install unitysvc-services
+```
+
+Requires Python 3.11+
+
+## Quick Example
+
+```bash
+# Initialize provider and service
+unitysvc_services init provider my-provider
+unitysvc_services init offering my-service
+unitysvc_services init seller my-marketplace
+
+# Validate and format
+unitysvc_services validate
+unitysvc_services format
+
+# Publish to platform
+export UNITYSVC_BACKEND_URL="https://api.unitysvc.com/api/v1"
+export UNITYSVC_API_KEY="your-api-key"
+
+unitysvc_services publish providers
+unitysvc_services publish sellers
+unitysvc_services publish offerings
+unitysvc_services publish listings
+
+# Verify
+unitysvc_services query offerings
+```
+
+## Key Features
+
+- 📋 **Pydantic Models** - Type-safe data models for all entities
+- ✅ **Data Validation** - Comprehensive schema validation
+- 🔄 **Local-First** - Work offline, commit to git, publish when ready
+- 🚀 **CLI Tools** - Complete command-line interface
+- 🤖 **Automation** - Script-based service generation
+- 📝 **Multiple Formats** - Support for JSON and TOML
+
+## Workflows
+
+### Manual Workflow (small catalogs)
+
+```bash
+init → edit files → validate → format → publish → verify
+```
+
+### Automated Workflow (large/dynamic catalogs)
+
+```bash
+init provider → configure populate script → populate → validate → publish
+```
+
+See [Workflows Documentation](https://unitysvc-services.readthedocs.io/en/latest/workflows/) for details.
+
+## Data Structure
+
+```
+data/
+├── seller.json                    # One seller per repo
+├── ${provider_name}/
+│   ├── provider.json              # Provider metadata
+│   ├── docs/                      # Shared documentation
+│   └── services/
+│       └── ${service_name}/
+│           ├── service.json       # Service offering
+│           └── listing-*.json     # Service listing(s)
+```
+
+See [Data Structure Documentation](https://unitysvc-services.readthedocs.io/en/latest/data-structure/) for complete details.
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `init` | Initialize new data files from schemas |
+| `list` | List local data files |
+| `query` | Query backend API for published data |
+| `publish` | Publish data to backend |
+| `update` | Update local file fields |
+| `validate` | Validate data consistency |
+| `format` | Format data files |
+| `populate` | Execute provider populate scripts |
+
+Run `unitysvc_services --help` or see [CLI Reference](https://unitysvc-services.readthedocs.io/en/latest/cli-reference/) for complete documentation.
+
+## Documentation
+
+- **[Getting Started](https://unitysvc-services.readthedocs.io/en/latest/getting-started/)** - Installation and first steps
+- **[Data Structure](https://unitysvc-services.readthedocs.io/en/latest/data-structure/)** - File organization rules
+- **[Workflows](https://unitysvc-services.readthedocs.io/en/latest/workflows/)** - Manual and automated patterns
+- **[CLI Reference](https://unitysvc-services.readthedocs.io/en/latest/cli-reference/)** - All commands and options
+- **[File Schemas](https://unitysvc-services.readthedocs.io/en/latest/file-schemas/)** - Schema specifications
+- **[Python API](https://unitysvc-services.readthedocs.io/en/latest/api-reference/)** - Programmatic usage
+
+## Links
+
+- **PyPI**: https://pypi.org/project/unitysvc-services/
+- **Documentation**: https://unitysvc-services.readthedocs.io
+- **Source Code**: https://github.com/unitysvc/unitysvc-services
+- **Issue Tracker**: https://github.com/unitysvc/unitysvc-services/issues
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions welcome! See [Contributing Guide](https://unitysvc-services.readthedocs.io/en/latest/contributing/) for details.