# Overview

Every page here is generated by `sphinx.ext.autodoc` from the docstrings in
`src/pycosmicsdk/`. Nothing is transcribed by hand, so a signature or a
`Raises:` list cannot drift from the code — edit the docstring and the page
changes. Docstring coverage is enforced in CI (`interrogate` at 95%) and
docstring/signature agreement by `pydoclint`.

## The public surface

Everything documented here is importable straight from the top-level package:

```python
from pycosmicsdk import Device, I2cBus, I2cError
```

The one exception is `pycosmicsdk.testing`, the test-support package, which is
imported from its own submodule so it never loads in production:
`from pycosmicsdk.testing import FakeAdapter`. See
{doc}`../guides/testing`.

The `pycosmicsdk.__all__` list is the contract. Modules whose names begin with
an underscore — `_interfaces`, `_cpp`, `_dispatcher`, `_async_engine` and the
rest — are internal, and so is the compiled `_pycosmicsdk_cpp` extension. They
are not documented here and their contents can change without notice, even
though the interface *classes* they define are public and appear below under
their public `pycosmicsdk.` names.

| Page | Contents |
|---|---|
| [Device and discovery](device.md) | {py:obj}`~pycosmicsdk.Device`, {py:obj}`~pycosmicsdk.AsyncDevice`, {py:obj}`~pycosmicsdk.list_devices`, {py:obj}`~pycosmicsdk.DiscoveredDevice` |
| [Debug probe](debugprobe.md) | {py:obj}`~pycosmicsdk.DebugProbe`, {py:obj}`~pycosmicsdk.AsyncDebugProbe`, {py:obj}`~pycosmicsdk.list_debug_probes` |
| [Protocol interfaces](interfaces.md) | The seven interface classes and their async twins |
| [Errors](errors.md) | The exception hierarchy |
| [Enums](enums.md) | Configuration enums and {py:obj}`~pycosmicsdk.StatusCode` |
| [Data types](types.md) | Capabilities, device info, and the per-protocol records |
| [Notifications](notifications.md) | Event types and {py:obj}`~pycosmicsdk.Subscription` |

## Not documented here

**The legacy compatibility shims.** `pycosmicsdk.legacy.supernovasdk`,
`pycosmicsdk.legacy.pulsarsdk` and `pycosmicsdk.legacy.supernovacontroller`
reproduce three legacy packages' APIs so existing scripts keep running after an
import-line change. They are a migration path, not the recommended API, and
each emits a `DeprecationWarning` on import. Their API *is* the legacy API, so
documenting it again here would be the wrong reference: see
the [migration guide](../migration.md) instead.

**The C++ layer.** The `nanobind` extension and the C++ facades below it are
implementation. The typed stubs shipped as `_cpp/_pycosmicsdk_cpp.pyi` are what
type checkers read; the C/C++ APIs themselves are documented in
[CosmicSDK](https://github.com/binhollc/CosmicSDK).