Skip to content

feat(cli): camelot-py alias, infer --format from --output ext, document the output template - #738

Merged
bosd merged 2 commits into
camelot-dev:masterfrom
bosd:feat/639-cli-uvx
May 20, 2026
Merged

bosd merged 2 commits into
camelot-dev:masterfrom
bosd:feat/639-cli-uvx

Conversation

@bosd

@bosd bosd commented May 20, 2026

Copy link
Copy Markdown
Collaborator

Closes #639.

Three usability improvements requested by @Lucas-C in #639:

camelot-py script alias

uvx camelot-py … now works directly. camelot-py is an alias for the same entry point as camelot — matches the PyPI package name, so users don't have to remember the longer uvx --from camelot-py camelot … form.

--format inferred from --output extension

--format is now optional. Each subcommand calls a shared _infer_format(output, explicit) helper that:

  • Honours an explicit --format (no behaviour change).
  • Else maps the --output extension to a known format (.csv/.xlsx/.xls/.html/.htm/.json/.md/.markdown/.sqlite/.sqlite3/.db).
  • Else returns None, falling through to the existing "specify --format" error.

So this works:

camelot-py lattice --output tables.xlsx document.pdf
# equivalent to: camelot-py lattice --format excel --output tables.xlsx document.pdf

--output documented as a template

The name-page-{P}-table-{T}.{ext} rule was always there but undocumented; surprising for new users. The option help now says so explicitly, and a dedicated docs section in docs/user/cli.rst shows the produced file pattern with a worked example.

What I deliberately did NOT do

  • The fourth request (camelot lattice --output … file.pdf shape: options on the subcommand) already works as of Feat: Make CLI options position-independent #614. No change needed.
  • The fifth request (make hybrid the default flavor) is a behaviour change that affects every existing CLI script. Deferred for an explicit follow-up issue if there's appetite — that one is not small.

Thanks @Lucas-C for the focused feedback.

bosd added 2 commits May 20, 2026 14:14
…e template (camelot-dev#639)

Three usability improvements requested in camelot-dev#639 (by @Lucas-C):

* Add a 'camelot-py' console script alias matching the PyPI package
  name, so 'uvx camelot-py …' works without the longer
  'uvx --from camelot-py camelot …' invocation.

* Make --format optional. When omitted, the format is inferred from
  the --output path's extension (.csv, .xlsx, .html, .json, .md,
  .sqlite, etc.). All four flavors share the same inference helper.

* Document --output as a *template* in the option help and add a
  dedicated docs section. The 'name-page-{P}-table-{T}.{ext}' rule
  has always been there but wasn't documented; surprising new users.

Adds a docs section for uvx usage alongside the format-inference and
output-template explanations.

The fourth request in camelot-dev#639 (options on subcommand: 'camelot lattice
--format … filepath') already works as of camelot-dev#614 — no change needed.

The fifth request (making 'hybrid' the default flavor) is a behavior
change that affects every existing CLI script; deferred for an
explicit follow-up issue if there's appetite.
…ev#639 inference

The four flavor tests (lattice/stream/hybrid/network) asserted that
invoking 'cli subcmd --output <.csv> <pdf>' (no --format) emits the
'Please specify output file format using --format' error. With camelot-dev#639
that error no longer fires for those calls — the format is inferred
from the .csv extension and the parse succeeds.

For each subcommand:
- swap the failure assertion for a 'Found N tables' success
  assertion, documenting the new inference behaviour
- (lattice only) add an extra invocation with a .ext-less --output
  path to confirm the format error STILL fires when the extension
  is unknown, locking in the fallback semantics
@bosd bosd added the enhancement New feature or request label May 20, 2026
@bosd
bosd merged commit 5f6b1e0 into camelot-dev:master May 20, 2026
19 checks passed
@bosd
bosd deleted the feat/639-cli-uvx branch May 25, 2026 13:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Suggestions regarding CLI usability & compatibility with uvx

1 participant