---
name: python-getting-started
description: APIMatic-generated Python SDK (APIMATIC v3.0, built on apimatic-core + apimatic-requests-client-adapter) reference and grounding layer — the PyPI package name from pyproject.toml, the single GiteaClient class in gitea_client.py constructed with keyword args (credentials objects + environment= + http/config kwargs), the Configuration class with Environment/Server enums, controllers accessed via @LazyProperty on the client, the APIException base, the HttpCallBack test seam, the from_environment() class method, and how to navigate the generated source. Entry point into the companion python-* skills (client-initialization, authentication, calling-endpoints, models, error-handling, configuration-resilience, testing) — gates loading each at its integration step, since the source shows signatures but not the usage gotchas these skills carry.
---

# Getting started with an APIMatic-generated Python SDK

> Controller classes are `{Resource}Api` and are reached as `@LazyProperty` attributes on the
> client — `client.{resource}` — never constructed directly. The `Api` suffix is a generator
> setting, so **confirm it** from the class names under `gitea/apis/`.

> `GiteaClient` is the SDK's client class — **read the real name** from `gitea/gitea_client.py`
> (it is derived from the package name, not the API title, so do not guess it from the API name).

This is the **SDK-specific** reference and grounding layer, and the entry into the companion
`python-*` skills. These SDKs are produced by **APIMATIC v3.0** (every generated file carries a
`This file was automatically generated by APIMATIC v3.0` header) and are built on the shared runtime
packages `apimatic-core`, `apimatic-core-interfaces`, and `apimatic-requests-client-adapter`. For the
general patterns that apply to *any* such SDK (client setup, auth, calling endpoints, models, error
handling, retries, testing), see the companion API-agnostic skills: `python-client-initialization`,
`python-authentication`, `python-calling-endpoints`, `python-models`, `python-error-handling`,
`python-configuration-resilience`, `python-testing`.

**The source and these companion skills are complementary — load both.** The generated source is
authoritative for the SDK's *surface* (constructor keyword args, enum values, which exception a
controller raises, model field names); the companion skills are the *usage layer* on top — the right
way to call each piece and the gotchas a signature can't show. Reading the source doesn't remove the
need to load the skill for that step, so at each step below load the companion *and* confirm names
against the source.

> **Before writing any integration code, clone the SDK source** (one command, in the *SDK source*
> section below) and read it to confirm every constructor signature, model field, enum value, and
> exception type as you go. Do **not** copy the SDK source into your project, and do **not** fetch
> GitHub files ad hoc — clone once, then grep the local copy. It's a throwaway reference: delete it
> when the integration is done.

## SDK identity

| | |
| --- | --- |
| API | `gitea` |
| Generator | APIMATIC v3.0 (`This file was automatically generated by APIMATIC v3.0` header on every file) |
| Runtime dependencies | `apimatic-core`, `apimatic-core-interfaces`, `apimatic-requests-client-adapter`, `python-dotenv`, `deprecation` — see `pyproject.toml` `dependencies` |
| PyPI package name | the `name` field in `pyproject.toml` (e.g. `multiauthsample`, `batester`) — per-API |
| Install | `pip install "git+https://github.com/context-plugins/gitea-python-sdk@main"` |
| Client class | `GiteaClient` in `gitea/gitea_client.py`, constructed with keyword arguments |
| Configuration class | `Configuration` in `gitea/configuration.py` (subclasses `HttpClientConfiguration`) |
| Auth | `{Scheme}Credentials` objects passed as keyword args to the client constructor — see **python-authentication** |
| Environment | `Environment` enum in `configuration.py` — read it for the real member names |
| Controllers | `@LazyProperty` properties on `GiteaClient` (e.g. `client.authentication`, `client.transaction`) |
| Return type | operations return a typed model or primitive directly; paginated operations return `PagedIterable` |
| Base exception | `APIException` in `gitea/exceptions/api_exception.py` — raised on non-2xx |
| HTTP runtime | `apimatic-requests-client-adapter` wrapping `requests` |
| Python version | `>=3.7` per `pyproject.toml` `requires-python` |

The table above is **orientation, not a copy-paste recipe** — it gives you the names and facts (PyPI
id, client class, `Configuration`, auth *pattern*, environments), while the actual integration code
comes from the companion skills. Load each one as you reach its step (see **Integration workflow**
below) and confirm its types against the cloned source.

## Package layout

APIMatic Python SDKs use a single top-level package named after the API (e.g. `multiauthsample`,
`batester`, `typecombinatorglobal`):

- `gitea/gitea_client.py` — the `GiteaClient` class: `__init__` keyword args, `from_environment()`
  class method, `@LazyProperty` controller property accessors, and (for OAuth) auth manager properties.
- `gitea/configuration.py` — `Configuration` class (subclasses `HttpClientConfiguration`),
  `Environment` enum, `Server` enum, `get_base_uri()`, `from_environment()`, and `clone_with()`.
- `gitea/api_helper.py` — `APIHelper` (subclasses `CoreApiHelper`): `json_deserialize`,
  `json_serialize`, `SKIP` sentinel for optional model fields, datetime helpers.
- `gitea/controllers/` — one `{Resource}Api` per API resource group, all inheriting from
  `base_controller.py`; operations are synchronous methods returning typed values or raising `APIException`.
- `gitea/models/` — model classes with `from_dictionary(cls, dict)`, `_names` / `_optionals` class
  attributes, and `additional_properties`; enum classes with `MEMBER = value` attributes.
- `gitea/exceptions/` — `APIException` base and typed subclasses (when the API documents error
  schemas); subclasses parse their body fields in `unbox()`.
- `gitea/http/` — `HttpCallBack` (the test seam), `HttpResponse`, `HttpRequest`, `HttpMethodEnum`,
  auth handlers under `auth/`, and `proxy_settings.py`.
- `gitea/utilities/` — `FileWrapper` for multipart uploads; `union_type_lookup.py` (when the API
  uses oneOf/anyOf).
- `gitea/logging/` — `LoggingConfiguration`, `RequestLoggingConfiguration`,
  `ResponseLoggingConfiguration` (generated when the API enables SDK logging).

## Install

```bash
pip install "git+https://github.com/context-plugins/gitea-python-sdk@main"
```

```python
from gitea.gitea_client import GiteaClient
from gitea.configuration import Environment
from gitea.exceptions.api_exception import APIException
```

Everything is importable via full dotted paths; `pip install` also pulls in the `apimatic-core*`
and `apimatic-requests-client-adapter` runtime packages transitively.

## SDK source — clone it first; don't fetch files ad hoc

You will constantly need to confirm real constructor kwargs, model field names, enum values, and
exception types, and the **only reliable way** is to read the SDK source. Clone it once, up front —
before writing integration code — into your **system temp directory** (outside your project), then
read and grep the local copy. It is a read-only, throwaway reference:

```bash
# Linux / macOS:
git clone --depth 1 --branch main https://github.com/context-plugins/gitea-python-sdk /tmp/gitea-python-src
```

```powershell
# Windows (PowerShell):
git clone --depth 1 --branch main https://github.com/context-plugins/gitea-python-sdk "$env:TEMP\gitea-python-src"
```

Then confirm the SDK shape **only** from that local clone:

- **Don't fetch GitHub files one at a time** — `…/blob/…` pages return HTML and guessed paths fail.
  Clone once and read locally. Only if `git` is unavailable, fetch a **raw** URL of the form
  `https://raw.githubusercontent.com/{owner}/{repo}/{branch}/…` (never a `…/blob/…` page).

Layout — grep the clone here first:

- `pyproject.toml` — the PyPI `name`, `requires-python`, and the runtime `dependencies`.
- `gitea/configuration.py` — `Configuration.__init__` kwargs, `Environment` enum values, `Server`
  enum, env-var names in `from_environment()`, and the base-URL template in `environments`.
- `gitea/gitea_client.py` — `GiteaClient.__init__` kwargs, `from_environment()`, and the
  `@LazyProperty` controller property names.
- `gitea/controllers/*.py` — operation method signatures, parameter names, and return types.
- `gitea/models/` — model `__init__` args, `_names`, `_optionals`, `from_dictionary()`, enum values.
- `gitea/exceptions/` — `APIException` and typed subclasses.
- `README.md` and `doc/` — generated human-readable index: `doc/client.md`, `doc/auth/*.md`,
  `doc/controllers/*.md`, `doc/models/*.md`, `doc/http-response.md`.
  **Grep `doc/` first** — fastest way to find an operation and its parameters, then open the `.py`
  file for the exact signature.

Clean up when done:

```bash
rm -rf /tmp/gitea-python-src                               # Linux / macOS
```
```powershell
Remove-Item -Recurse -Force "$env:TEMP\gitea-python-src"   # Windows
```

## Integration workflow — load the companion skill at each step

Before you write the code for each step, load the named companion skill — even if you've already read
the relevant source. Each step calls out the trap the signature hides (in *parens*).

1. **Client construction** — load **python-client-initialization** before you call `GiteaClient(...)`.
   (*The signature won't tell you:* all arguments are keyword-only; credentials are `{Scheme}Credentials`
   objects — not raw strings — passed by keyword; `from_environment()` reads a `.env` file and env vars;
   controllers are `@LazyProperty` properties on the client, not classes you instantiate yourself.)
2. **Authentication** — load **python-authentication** before you set credentials. (*The signature
   won't tell you:* each scheme is a `{Scheme}Credentials` object with its own `clone_with()`;
   OAuth CCG/ROPCG tokens are fetched automatically on first use; token persistence uses the
   `o_auth_on_token_update` callback; the token is re-attached via `config.clone_with()` + a new client.)
3. **Calling an endpoint** — load **python-calling-endpoints** before the first
   `client.{resource}.{operation}(...)` call. (*The signature won't tell you:* the controller is a
   `@LazyProperty` property on the client — access it as `client.{resource}`, not a constructor call;
   all parameters are passed by keyword; optional params default to `APIHelper.SKIP`, not `None`;
   return values are typed model instances or primitives; paginated operations return `PagedIterable`.)
4. **Models** — load **python-models** the moment a request/response field isn't a plain string or
   number. (*The signature won't tell you:* optional constructor args use `APIHelper.SKIP` as their
   sentinel — checking `hasattr` is needed on response objects; enums are plain classes with integer
   or string class attributes; oneOf/anyOf union types are deserialized by the SDK via
   `UnionTypeLookUp` and `validate()` — you pass the plain value and the SDK resolves it;
   unknown JSON keys land in `additional_properties`.)
5. **Error handling** — load **python-error-handling** before your first `try/except`. (*The signature
   won't tell you:* a non-2xx raises `APIException` (or a typed subclass); `.response_code` holds the
   HTTP status; `.response` holds the raw `HttpResponse` with `.text` and `.headers`; typed subclasses
   call `unbox()` at construction to parse body fields.)
6. **Configuration & resilience** — load **python-configuration-resilience** when you tune retries,
   timeouts, a custom HTTP client, or the base URL. (*The signature won't tell you:* retries are
   **disabled by default** (`max_retries=0`); only `GET`/`PUT` are retried when enabled; pass a custom
   `requests.Session` via `http_client_instance`; structured logging uses `LoggingConfiguration`.)
7. **Testing** — load **python-testing** before you stub the SDK. (*The signature won't tell you:*
   the primary test seam is `HttpCallBack` — subclass it, implement `on_before_request` /
   `on_after_response`, and pass the instance as `http_call_back=`; or stub at the `requests` transport
   level with the `responses` library or `unittest.mock`.)