Metadata-Version: 2.4
Name: sweetconnect-api
Version: 0.2.0
Summary: A SweetConnect API library for Python
Author-email: Kai CLauss <kc@sweetconnect.io>, Eduardo Melgarejo <eduardo.melgarejo@sollich.com>, Felix Weisenfeld <felix.weisenfeld@w-u-d.com>
License: GPL-3.0
License-File: LICENSE
Requires-Python: >=3.8
Requires-Dist: click>=8.0.1
Requires-Dist: loguru>=0.6.0
Requires-Dist: pydantic<2.0.0,>=1.9.1
Description-Content-Type: text/markdown

# SweetConnect API Library

<!-- Uncomment if implemented!
[![PyPI](https://img.shields.io/pypi/v/sweetconnect-api.svg)][pypi_]
[![Read the documentation at https://sweetconnect-api.readthedocs.io/](https://img.shields.io/readthedocs/sweetconnect-api/latest.svg?label=Read%20the%20Docs)][read the docs]
[![Tests](https://gitlab.com/sweetconnect/public/sweetconnect-api/workflows/Tests/badge.svg)][tests]
[![Codecov](https://codecov.io/gh/cjolowicz/sweetconnect-api/branch/main/graph/badge.svg)][codecov]
 -->

[![Status](https://img.shields.io/badge/status-Alpha-orange)][status]
[![License](https://img.shields.io/badge/license-GPL_3.0-green)][license]
[![Python Version](https://img.shields.io/badge/python-%3E%3D%203.8-blue)][python version]
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)][pre-commit]
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)][ruff]

<!-- [pypi_]: https://pypi.org/project/sweetconnect-api/
[read the docs]: https://sweetconnect-api.readthedocs.io/
[tests]: https://gitlab.com/sweetconnect/public/sweetconnect-api/actions?workflow=Tests
[codecov]: https://app.codecov.io/gh/cjolowicz/sweetconnect-api
 -->

[status]: https://pypi.org/project/sweetconnect-api/
[python version]: https://pypi.org/project/sweetconnect-api
[pre-commit]: https://github.com/pre-commit/pre-commit
[ruff]: https://github.com/astral-sh/ruff

## Installation

You can install _SweetConnect API Library_ via [pip] from [PyPI]:

```console
$ pip install sweetconnect-api
```

## Quick Start

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

```python
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/](examples/) directory in the repository.

## Development

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

```console
# 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 .
```

[uv]: https://github.com/astral-sh/uv

### Testing Local Builds

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

```console
# 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](https://github.com/astral-sh/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:

```console
# 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](https://github.com/ofek/hatch-vcs) for automatic version management based on Git tags, following [Semantic Versioning](https://semver.org/) (SemVer) with [PEP 440](https://peps.python.org/pep-0440/) 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`.

<details>
<summary><strong>📦 Creating a Pre-Release (Alpha/Beta/RC)</strong></summary>

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

```console
# 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
```

</details>

<details>
<summary><strong>🚀 Creating a Stable Release</strong></summary>

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

```console
# 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
```

</details>

### 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:**

```console
# 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][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.

[@cjolowicz]: https://github.com/cjolowicz
[pypi]: https://pypi.org/
[hypermodern python cookiecutter]: https://github.com/cjolowicz/cookiecutter-hypermodern-python
[hypermodern python documentation]: https://cookiecutter-hypermodern-python.readthedocs.io/
[file an issue]: https://bitbucket.org/sweetconnect/sweetconnect-api-library-python/jira
[pip]: https://pip.pypa.io/

<!-- github-only -->

[license]: https://bitbucket.org/sweetconnect/sweetconnect-api-library-python/src/main/LICENSE
[contributor guide]: https://bitbucket.org/sweetconnect/sweetconnect-api-library-python/src/main/CONTRIBUTING.md
[command-line reference]: https://sweetconnect-api.readthedocs.io/en/latest/usage.html
