Skip to content

AGENTS.md

Latest commit

 

History

History
135 lines (104 loc) · 6.56 KB

AGENTS.md

File metadata and controls

135 lines (104 loc) · 6.56 KB
Raw

MyCli

A command line client for MySQL with auto-completion and syntax highlighting.

Project Structure

/ # repository root ├── .github/ # GitHub Actions and configuration ├── pyproject.toml # project configuration ├── doc/ # documentation ├── mycli/ # application source ├── mycli/init.py # provides version number ├── mycli/app_state.py # AppStateMixin application state mixin and related functions ├── mycli/cli_runner.py # connects and dispatches main modes based on CLI arguments ├── mycli/clibuffer.py # prompt_toolkit buffer utilities ├── mycli/client_commands.py # special commands which must be registered separately ├── mycli/client_connection.py # ClientConnectionMixin mixin for establishing the database connection ├── mycli/client_query.py # ClientQueryMixin mixin for running queries and refreshing completions ├── mycli/client.py # the MyCli "god class" ├── mycli/clistyle.py # prompt_toolkit style utilities ├── mycli/clitoolbar.py # prompt_toolkit toolbar utilities ├── mycli/compat.py # OS compatibility helpers ├── mycli/completion_refresher.py # populates a SQLCompleter object in a background thread ├── mycli/config.py # configuration file readers and utilities ├── mycli/constants.py # shared constants ├── mycli/key_bindings.py # prompt_toolkit key binding utilities ├── mycli/lexer.py # extends MySqlLexer from Pygments ├── mycli/main.py # processes CLI arguments ├── mycli/main_modes/ # main execution paths ├── mycli/main_modes/batch.py # --batch mode ├── mycli/main_modes/checkup.py # --checkup mode ├── mycli/main_modes/execute.py # --execute mode ├── mycli/main_modes/list_dsn.py # --list-dsn mode ├── mycli/main_modes/repl.py # interactive REPL mode ├── mycli/myclirc # project-level configuration file ├── mycli/output.py # OutputMixin mixin for feedback and output of query results ├── mycli/packages/ # application packages ├── mycli/packages/batch_utils.py # utilities for --batch mode ├── mycli/packages/cli_utils.py # utilities for parsing CLI arguments ├── mycli/packages/completion_engine.py # implementation of completion suggestions ├── mycli/packages/filepaths.py # utilities for files, including completion suggestions ├── mycli/packages/hybrid_redirection.py # implementation of shell-style redirects ├── mycli/packages/interactive_utils.py # utilities for confirming on destructive statements ├── mycli/packages/key_binding_utils.py # handlers for key bindings and related special commands ├── mycli/packages/sql_utils.py # utilities for parsing SQL statements ├── mycli/packages/ptoolkit/ # extends prompt_toolkit ├── mycli/packages/special/ # implementation of mycli special commands ├── mycli/packages/sqlresult.py # the SQLResult dataclass for holding responses ├── mycli/packages/string_utils.py # generic string utilities ├── mycli/packages/tabular_output/ # extends cli_helper with additional output formats ├── mycli/password_sources.py # password sources and precedence ├── mycli/ssh_tunnel.py # connecting over a tunnel with --ssh-jump ├── mycli/schema_prefetcher.py # background prefetcher for multi-schema auto-completion ├── mycli/sqlcompleter.py # offers SQL completions ├── mycli/sqlexecute.py # runs SQL queries ├── mycli/types.py # shared types ├── mycli/vault.py # Vault integration ├── test/features/ # behave tests ├── test/myclirc # mycli configuration used for tests ├── test/mylogin.cnf # mylogin.cnf example used for tests ├── test/pytests/ # pytest tests ├── test/pytests/conftest.py # pytest configuration └── test/utils.py # shared utilities for tests

Development

Python

Python Dependency Management

This repo uses uv for dependency management. Always prefix Python commands with uv run. Example:

uv run -- python script.py

Python Typing

This repo uses type annotations which are checked by mypy. Always add type annotations, and always check new code with uv run -- mypy --install-types --non-interactive script.py.

Use lower-case type annotations such as tuple, not upper-case type annotations such as Tuple.

Use Type | None instead of Optional[Type].

Python Testing

Tests are coordinated by tox, and include both pytest and behave tests. To run the full test suite, execute uv run -- tox.

Python Compatibility

Use Python features available from Python 3.10 through Python 3.14. Compatibility with Python 3.9 is not needed.

Python Style

Import style: prefer from package import name over import package.name as name.

Quoting style: prefer single quotes for new code, but do not remove double quotes from existing code.

Python Environment

  • Package manager: uv (not pip)
  • Formatter: uv run -- ruff format
  • Linter: uv run -- ruff check
  • Type checker: uv run -- mypy --install-types --non-interactive

Git Workflows

Git Commit Messages

  • Use the present tense.
  • Keep the first line under 50 characters in length.
  • Keep the second line blank.
  • Keep all other lines under 72 characters in length.
  • Reference issue numbers when available.

Generating PRs

When generating a PR, follow the instructions in .github/PULL_REQUEST_TEMPLATE.md:

  • Add new author names to mycli/AUTHORS.
  • Add a new entry to changelog.md.

Code Comments

Keep comments concise and direct. Use full sentences, ending with a period.

See Also

See also the file CONTRIBUTING.md.