Getting Started¶

1. Installation¶

octopolars is on PyPI. Install with:

pip install octopolars[polars]

Using uv (optional)

If you set up uv (recommended for a smoother developer experience), you can install with:

uv pip install octopolars[polars]

or set up a project (e.g., uv init --app --package, uv venv, then activate the venv), and add octopolars:

uv add octopolars[polars]

2. Usage¶

octopolars provides a CLI tool called octopols. To list a user’s GitHub repositories:

octopols my-username

To apply filters or walk files instead of list repos, add flags. For example:

octopols my-username -w --filter '{name}.str.startswith("d3")'

This will list only files from repositories whose name starts with "d3".

More CLI Examples¶

List repos with a name filter:

octopols my-username -f '{name}.str.contains("demo")'

List files non-recursively:
```
octopols my-username -w
```

List all files, output to CSV:

octopols my-username -w -output-format csv

For advanced usage like limiting rows/columns, see the CLI reference.

3. Local Development¶

Clone the Repo:

git clone https://github.com/lmmx/octopolars.git

Install Dependencies: - If you’re using pdm:
```
pdm install
```
- Otherwise, standard pip:
```
pip install -e .
```
Optional: Pre-commit Hooks:
```
pre-commit install
```
This automatically runs lint checks (e.g., black, flake8) before each commit.
Run Tests (if applicable):
```
pytest
```
Build/Serve Docs (if included):
```
mkdocs serve
```
Then visit the local server link. Use mkdocs gh-deploy to publish on GitHub Pages.

4. Example Workflow¶

List Repositories:
```
octopols octo-user
```

Apply a Filter:

octopols octo-user --filter='{name}.str.startswith("demo")'

Switch to Files:
```
octopols octo-user --walk
```

Combine Steps:

octopols octo-user -F --filter='pl.col("file_path").str.contains(".md")'

This filters file trees in each repository for Markdown files.

5. Configuration¶

octopolars primarily relies on: - GH_TOKEN: Recommended to avoid low rate limits, or else requires gh to be installed. - Caching: By default, it caches your repos in a user-specific cache directory. - CLI Flags: Control recursion, output format, table dimensions, and more via flags: - --rows, --cols, --quiet: Manage table display size. - --filter: Apply a Polars-based filter or DSL expression.

For further details, consult the API Reference or the help text:

octopols --help