sweetconnect-api 0.2.1

A SweetConnect API library for Python

SweetConnect API Library

Installation

You can install SweetConnect API Library via pip from PyPI:

$ pip install sweetconnect-api

Quick Start

Here's a simple example to get you started with the SweetConnect API:

from sweetconnect_api import SweetConnectSession
from sweetconnect_api.assets import Assets

# Initialize a session
session = SweetConnectSession(
    base_url="https://api.my.sweetconnect.io",
    username="your_username",
    password="your_password"
)

# Access assets
assets_api = Assets(session)
assets = assets_api.get_all()

# Work with your data
for asset in assets:
    print(f"Asset: {asset.name} (ID: {asset.assetId})")

For more examples, see the examples/ directory in the repository.

Development

This project uses uv for dependency management. To set up a development environment:

# Install uv (if not already installed)
$ curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
$ git clone https://bitbucket.org/sweetconnect/sweetconnect-api-library-python
$ cd sweetconnect-api-library-python

# Install dependencies
$ uv sync

# Run tests
$ uv run pytest

# Run linting checks (same as CI pipeline)
$ ./lint.sh

# Or run linting manually
$ uv run ruff check .
$ uv run ruff format .

Testing Local Builds

Before creating a release, you can test your local changes:

# Build the package locally
$ uv build

# Install the local build in a test environment
$ pip install dist/sweetconnect_api-*.whl

# Or test in an isolated environment
$ python -m venv test-env
$ source test-env/bin/activate  # On Windows: test-env\Scripts\activate
$ pip install dist/sweetconnect_api-*.whl

# Verify the installation
$ python -c "import sweetconnect_api; print(sweetconnect_api.__version__)"

# Clean up when done
$ deactivate
$ rm -rf test-env

Code Quality Notes

Linting: This project uses Ruff for linting and formatting.

Pre-commit Hooks: This project uses pre-commit hooks to ensure code quality before commits.

To set up pre-commit hooks:

# Install pre-commit hooks (one-time setup)
$ uv run pre-commit install

# Run hooks manually on all files
$ uv run pre-commit run --all-files

# Run hooks on staged files only (happens automatically on commit)
$ git commit

The pre-commit hooks will automatically check:

• Ruff: Code linting and formatting
• File checks: Large files, TOML/YAML syntax, trailing whitespace
• Secret detection: Prevents committing passwords, API keys, and private keys
• Prettier: Formats JSON/YAML/Markdown files

Design Decisions:

• API Naming: Models use mixedCase (e.g., assetId, tenantId) to match the SweetConnect REST API convention
• Examples: Star imports (from module import *) used in example files for brevity
• Docstrings: Optional for internal APIs (following project conventions)

Areas for Future Improvement:

• Add specific exception handling for bare except clauses
• Expand API documentation coverage

Versioning

This project uses hatch-vcs for automatic version management based on Git tags, following Semantic Versioning (SemVer) with PEP 440 compliance:

Version Format: MAJOR.MINOR.PATCH

• MAJOR: Breaking changes (not backwards compatible)
• MINOR: New features (backwards compatible)
• PATCH: Bug fixes (backwards compatible)

Version Types:

• Stable releases (e.g., 0.1.0): Created from Git tags (e.g., v0.1.0)
• Development versions (e.g., 0.1.1.dev4): Automatically generated between releases
• Alpha versions (e.g., 0.2.0a1): Early testing (tag: v0.2.0a1)
• Beta versions (e.g., 0.2.0b1): Feature-complete testing (tag: v0.2.0b1)
• Release candidates (e.g., 0.2.0rc1): Pre-release testing (tag: v0.2.0rc1)

Version Increment Guide:

• Patch (v0.1.1): Bug fixes only
• Minor (v0.2.0): New features, backwards compatible
• Major (v1.0.0): Breaking changes

Deployment Workflows:

The version is automatically determined from Git history - no manual version updates needed in pyproject.toml.

📦 Creating a Pre-Release (Alpha/Beta/RC)

Use pre-releases for testing new features before a stable release:

# 1. Ensure your changes are committed and pushed to main
$ git checkout main
$ git pull origin main

# 2. Create and push a pre-release tag
$ git tag v0.2.0a1        # Alpha release
$ git push origin v0.2.0a1

# 3. Bitbucket Pipeline automatically:
#    - Runs linting checks
#    - Builds the package
#    - Deploys to PyPI (production environment)

# 4. Test the pre-release
$ pip install sweetconnect-api==0.2.0a1

# 5. If issues found, fix them and create next pre-release
$ git tag v0.2.0a2
$ git push origin v0.2.0a2

# 6. Progress through testing phases
$ git tag v0.2.0b1        # Beta (feature complete)
$ git push origin v0.2.0b1

$ git tag v0.2.0rc1       # Release Candidate (final testing)
$ git push origin v0.2.0rc1

🚀 Creating a Stable Release

When all testing is complete and you're ready for production:

# 1. Ensure main branch is ready
$ git checkout main
$ git pull origin main

# 2. Create and push the release tag
$ git tag v0.2.0
$ git push origin v0.2.0

# 3. Bitbucket Pipeline automatically:
#    - Runs linting checks
#    - Builds the package
#    - Deploys to PyPI (production environment)

# 4. Verify the release on PyPI
$ pip install --upgrade sweetconnect-api

# 5. Update documentation/changelog if needed

Continuous Integration

This project uses Bitbucket Pipelines for CI/CD. The pipeline runs:

• Linting: Ruff checks code style and quality
• Type Checking: mypy is currently disabled due to too many type errors that need to be addressed
• Security: Safety checks are currently disabled
• Build: Creates distribution packages
• Deployment: Only deploys to PyPI when a v* tag is pushed to the production environment
  • Stable releases: v0.1.0, v0.2.0
  • Alpha releases: v0.2.0a1, v0.2.0a2
  • Beta releases: v0.2.0b1, v0.2.0b2
  • Release candidates: v0.2.0rc1, v0.2.0rc2

Note: The main branch runs CI checks (lint + build) but does not automatically deploy to PyPI. All deployments require an explicit version tag.

Setup Requirements:

To enable PyPI publishing, add the PYPI_TOKEN secret in Bitbucket:

1. Go to Repository Settings → Pipelines → Repository variables
2. Add variable: PYPI_TOKEN with your PyPI API token

Usage

Please see the Command-line Reference for details.

API Documentation

SweetConnect API documentation is available for different environments:

• Production: https://doc.api.my.sweetconnect.io/ - Stable API for production use
• Test: https://doc.api.test.sweetconnect.io/ - Testing environment for integration testing
• Development: https://doc.api.dev.sweetconnect.io/ - Development environment with latest features

Contributing

Contributions are very welcome! Here's how you can help:

1. Report Issues: File an issue with bug reports or feature requests
2. Submit Pull Requests: Fork the repository and submit PRs
3. Improve Documentation: Help expand the documentation
4. Code Review: Review and comment on open PRs

For detailed guidelines, see the Contributor Guide.

Development Setup:

# Fork and clone the repository
$ git clone https://bitbucket.org/<your-username>/sweetconnect-api-library-python
$ cd sweetconnect-api-library-python

# Set up development environment
$ uv sync
$ uv run pre-commit install

# Run tests and linting before committing
$ uv run pytest
$ ./lint.sh

This project was generated from @cjolowicz's Hypermodern Python Cookiecutter template. For more details see Hypermodern Python documentation

License

Distributed under the terms of the GPL 3.0 license, SweetConnect API Library is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.