Malloy Publisher Client

A Python client for interacting with the Malloy Publisher API. This client provides a type-safe interface for working with Malloy projects, packages, models, and executing queries.

Features

• Type-safe API client with Pydantic models
• Full support for Malloy Publisher API endpoints
• Async HTTP client using httpx
• Comprehensive error handling
• Context manager support for resource cleanup

Requirements

• Python 3.11 or higher
• UV package manager

Installation

You can install the package directly from PyPI:

pip install malloy-publisher-client
# or using uv
uv pip install malloy-publisher-client

For development installation:

1. Clone the repository:

git clone https://github.com/yourusername/malloy-publisher-client.git
cd malloy-publisher-client

2. Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate  # On Windows

3. Install dependencies using UV:

uv pip install -e ".[dev]"

Usage

Here's a basic example of how to use the client:

from malloy_publisher_client import MalloyAPIClient, QueryParams

# Initialize the client
client = MalloyAPIClient(
    base_url="https://your-malloy-publisher-url",
    api_key="your-api-key"  # Optional
)

# List all projects
projects = client.list_projects()

# List packages in a project
packages = client.list_packages("project_name")

# List models in a package
models = client.list_models("project_name", "package_name")

# Execute a query
query_params = QueryParams(
    project_name="project_name",
    package_name="package_name",
    path="model_path",
    query="your query here"
)
result = client.execute_query(query_params)

# Use as a context manager
with MalloyAPIClient(base_url="https://your-malloy-publisher-url") as client:
    # Your code here
    pass

Development

Setting Up Development Environment

1. Install development dependencies:

uv pip install -e ".[dev]"

2. Install pre-commit hooks (if configured):

pre-commit install

Code Style

This project uses:

• Black for code formatting
• MyPy for type checking
• Ruff for linting

To format code:

black .

To run type checks:

mypy .

To run linter:

ruff check .

Running Tests

The project uses pytest for testing. To run tests:

pytest

For verbose output:

pytest -v

Building and Publishing

To build the package:

# Clean previous builds
rm -rf dist/ build/ *.egg-info/

# Install build tools
uv pip install build twine

# Build the package
python -m build

To publish to PyPI:

1. Ensure you have a PyPI account and your credentials are configured in ~/.pypirc
2. Build the package as described above
3. Upload to PyPI:

python -m twine upload dist/*

4. Create a git tag for the release:

git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and ensure all checks pass
5. Commit your changes using conventional commits
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Guidelines

• Follow PEP 8 style guide
• Add type hints to all functions
• Write docstrings for all public functions and classes
• Add tests for new functionality
• Update documentation as needed

License

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