Metadata-Version: 2.4
Name: OdyUtils
Version: 0.0.1b1
Summary: Shared utilities for Odysseia cogs.
Home-page: https://github.com/everestmcarthur/OdyUtils
Author: everestmcarthur
License: GPL-3.0-or-later
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sentry_sdk
Requires-Dist: colorama
Requires-Dist: rich
Requires-Dist: aiohttp
Requires-Dist: packaging
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# OdyUtils

OdyUtils is a shared utility package for cogs running on
[Odysseia](https://github.com/everestmcarthur/RubyRed), a Red-DiscordBot
fork. It merges the useful parts of two reference utility packages -
[vex-cog-utils](https://github.com/Vexed01/vex-cog-utils) and
[AAA3A_utils](https://github.com/AAA3A-AAA3A/AAA3A_utils) - into one
package, adapted to build on top of Odysseia's own primitives instead of
duplicating them:

- Every response-building surface (menus, confirmations, prompts, settings
  displays, generated cog error messages) is built on Odysseia's
  **Components V2** toolkit (`odysseia.core.components`,
  `odysseia.core.utils.views`) - there are no embeds anywhere in this
  package, matching Odysseia's own CV2-only UI.
- Base classes (`OdyCog`) extend `odysseia.core.commands.Cog` rather than
  reimplementing what it already provides.
- Anything that duplicates functionality Odysseia already ships (its own
  `Context`, `SimpleMenu` paginator, select/modal/confirm builders, ...) was
  either dropped in favour of the existing implementation, or rebuilt as a
  thin layer on top of it. See each module's docstring for the specific
  keep/merge/adapt/drop rationale.

Notable pieces:

- `OdyCog` (`cog.py`) - a batteries-included cog base class: automatic
  typing indicator + tick/cross reaction per command, a verbose
  "which permission is actually missing" error handler, and a
  development-only-command confirmation gate.
- `CogsUtils`, `Loop`, `Settings`, `SentryHelper` - ported grab-bag
  utilities, version/update checking, a declarative settings framework, and
  opt-in error telemetry.
- `scaffold.py` - generates a new cog's `__init__.py` (dependency check,
  module-reload loop, end-user-data statement, `setup()`), styled after
  AAA3A_utils' own hand-written dependency-check pattern but rebranded for
  OdyUtils/Odysseia.

## Installation

```bash
pip install git+https://github.com/everestmcarthur/OdyUtils.git
```

For local development against an editable Odysseia checkout:

```bash
pip install -e /path/to/OdyUtils
```

## Credits

Substantial portions of this package's code are derived from, or directly
ported from, these two projects - full credit to their authors:

- [Vexed01/vex-cog-utils](https://github.com/Vexed01/vex-cog-utils)
- [AAA3A-AAA3A/AAA3A_utils](https://github.com/AAA3A-AAA3A/AAA3A_utils)

OdyUtils itself is not affiliated with either project; it's an
Odysseia-specific merge and adaptation of their ideas and code.
