atpcli 0.1.0__tar.gz

atpcli-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+env.ini
+.ruff_cache/
+.pytest_cache/
+.idea/
+__pycache__
+.DS_Store
+dist/
+htmlcov/
+*.coverage*
+coverage.xml
+.cache/
+*.pyc
+site/

atpcli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

atpcli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing
+
+First things first: thank you for contributing! This project will be successful thanks to everyone who contributes, and we're happy to have you.
+
+## Bug or issue?
+
+To raise a bug or issue please use [our GitHub](https://github.com/phalt/atpcli/issues).
+
+Please check the issue has not been raised before by using the search feature.
+
+When submitting an issue or bug, please make sure you provide thorough detail on:
+
+1. The version of atpcli you are using
+2. Any errors or outputs you see in your terminal
+3. Steps to reproduce the issue
+
+## Contribution
+
+If you want to directly contribute you can do so in two ways:
+
+1. Documentation
+2. Code
+
+### Documentation
+
+Fixing grammar, spelling mistakes, or expanding the documentation to cover features that are not yet documented, are all valuable contributions.
+
+### Code
+
+Contribution by writing code for new features, or fixing bugs, is a great way to contribute to the project.
+
+#### Set up
+
+Clone the repo:
+
+```sh
+git clone git@github.com:phalt/atpcli.git
+cd atpcli
+```
+
+Move to a feature branch:
+
+```sh
+git branch -B my-branch-name
+```
+
+Install UV (if not already installed):
+
+```sh
+# On macOS and Linux:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Or using pip:
+pip install uv
+```
+
+Install all the dependencies:
+
+```sh
+make install
+```
+
+This will use UV to create a virtual environment and install all dependencies. UV handles the virtual environment automatically, so you don't need to manually activate it.
+
+To make sure you have things set up correctly, please run the tests:
+
+```sh
+make test
+```
+
+### Preparing changes for review
+
+Once you've made changes, here's a good checklist to run through before publishing for review:
+
+Run tests:
+
+```sh
+make test
+```
+
+Format and lint the code:
+
+```sh
+make format
+```
+
+### Making a pull request
+
+Please push your changes up to a feature branch and make a new [pull request](https://github.com/phalt/atpcli/compare) on GitHub.
+
+Please add a description to the PR and some information about why the change is being made.
+
+After a review, you might need to make more changes.
+
+Once accepted, a core contributor will merge your changes!

atpcli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paul Hallett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

atpcli-0.1.0/Makefile

@@ -0,0 +1,37 @@
+help:
+	@echo Developer commands for atpcli
+	@echo
+	@grep -E '^[ .a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+	@echo
+
+install:  ## Install requirements ready for development
+	uv sync
+
+format: ## Format the code correctly
+	uv run ruff format .
+	uv run ruff check --fix .
+
+clean:  ## Clear any cache files and test files
+	rm -rf .pytest_cache
+	rm -rf .ruff_cache
+	rm -rf dist/
+	rm -rf **/__pycache__
+	rm -rf **/*.pyc
+	rm -rf htmlcov/
+	rm -rf .coverage
+	rm -rf site/
+
+test:  ## Run tests
+	uv run pytest -vvv -x --cov=atpcli --cov-report=term-missing --cov-report=html --cov-config=pyproject.toml
+
+docs-serve:  ## Run a local documentation server
+	uv run mkdocs serve
+
+docs-build:  ## Build the documentation
+	uv run mkdocs build
+
+shell:  ## Run a Python shell
+	uv run python
+
+release:  ## Build a new version and release it
+	uv build && uv publish

atpcli-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: atpcli
+Version: 0.1.0
+Summary: A Python CLI wrapper around the atproto package
+Project-URL: Homepage, https://github.com/phalt/atpcli
+Project-URL: Issues, https://github.com/phalt/atpcli/issues
+Author-email: Paul Hallett <paulandrewhallett@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: atproto>=0.0.55
+Requires-Dist: click>=8.1.7
+Requires-Dist: rich>=13.7.0
+Description-Content-Type: text/markdown
+
+# atpcli
+
+A Python CLI wrapper around the [atproto](https://github.com/MarshalX/atproto) package for interacting with Bluesky.
+
+## Documentation
+
+Full documentation is available at [docs/](docs/):
+
+- [Installation Guide](docs/install.md)
+- [Quick Start Guide](docs/getting-started.md) - Learn how to get app passwords and use atpcli
+- [Login Command](docs/usage-login.md)
+- [Timeline Command](docs/usage-timeline.md)
+
+Or serve the docs locally:
+
+```bash
+make docs-serve
+```
+
+## Quick Start
+
+### Installation
+
+Install globally using [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install atpcli
+```
+
+This installs `atpcli` as a global tool, making it available from anywhere in your terminal.
+
+Or for development:
+
+```bash
+git clone https://github.com/phalt/atpcli.git
+cd atpcli
+make install
+```
+
+## Usage
+
+### Login
+
+⚠️ **Security Note**: Use Bluesky app passwords, not your main password! See the [Quick Start Guide](docs/getting-started.md) for instructions on creating an app password.
+
+Login to your Bluesky account and save the session:
+
+```bash
+atpcli bsky login
+```
+
+You'll be prompted for your handle and password. The session will be saved to `~/.config/atpcli/config.json`.
+
+### View Timeline
+
+View your timeline:
+
+```bash
+atpcli bsky timeline
+```
+
+Options:
+- `--limit N` - Show N posts (default: 10)
+- `--p N` - Show page N (default: 1)
+
+Example:
+```bash
+atpcli bsky timeline --limit 20
+atpcli bsky timeline --p 2
+```
+
+## Development
+
+### Setup
+
+```bash
+make install
+```
+
+### Run tests
+
+```bash
+make test
+```
+
+### Build documentation
+
+```bash
+make docs-build
+```
+
+### Serve documentation locally
+
+```bash
+make docs-serve
+```
+
+### Format code
+
+```bash
+make format
+```
+
+### Clean build artifacts
+
+```bash
+make clean
+```
+
+## Requirements
+
+- Python 3.10+
+- uv package manager
+
+## License
+
+MIT

atpcli-0.1.0/README.md

@@ -0,0 +1,117 @@
+# atpcli
+
+A Python CLI wrapper around the [atproto](https://github.com/MarshalX/atproto) package for interacting with Bluesky.
+
+## Documentation
+
+Full documentation is available at [docs/](docs/):
+
+- [Installation Guide](docs/install.md)
+- [Quick Start Guide](docs/getting-started.md) - Learn how to get app passwords and use atpcli
+- [Login Command](docs/usage-login.md)
+- [Timeline Command](docs/usage-timeline.md)
+
+Or serve the docs locally:
+
+```bash
+make docs-serve
+```
+
+## Quick Start
+
+### Installation
+
+Install globally using [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install atpcli
+```
+
+This installs `atpcli` as a global tool, making it available from anywhere in your terminal.
+
+Or for development:
+
+```bash
+git clone https://github.com/phalt/atpcli.git
+cd atpcli
+make install
+```
+
+## Usage
+
+### Login
+
+⚠️ **Security Note**: Use Bluesky app passwords, not your main password! See the [Quick Start Guide](docs/getting-started.md) for instructions on creating an app password.
+
+Login to your Bluesky account and save the session:
+
+```bash
+atpcli bsky login
+```
+
+You'll be prompted for your handle and password. The session will be saved to `~/.config/atpcli/config.json`.
+
+### View Timeline
+
+View your timeline:
+
+```bash
+atpcli bsky timeline
+```
+
+Options:
+- `--limit N` - Show N posts (default: 10)
+- `--p N` - Show page N (default: 1)
+
+Example:
+```bash
+atpcli bsky timeline --limit 20
+atpcli bsky timeline --p 2
+```
+
+## Development
+
+### Setup
+
+```bash
+make install
+```
+
+### Run tests
+
+```bash
+make test
+```
+
+### Build documentation
+
+```bash
+make docs-build
+```
+
+### Serve documentation locally
+
+```bash
+make docs-serve
+```
+
+### Format code
+
+```bash
+make format
+```
+
+### Clean build artifacts
+
+```bash
+make clean
+```
+
+## Requirements
+
+- Python 3.10+
+- uv package manager
+
+## License
+
+MIT

atpcli-0.1.0/atpcli/__init__.py

@@ -0,0 +1,3 @@
+"""atpcli - A Python CLI wrapper around the atproto package."""
+
+__version__ = "0.1.0"

atpcli-0.1.0/atpcli/cli.py

@@ -0,0 +1,135 @@
+"""CLI commands for atpcli."""
+
+import textwrap
+
+import click
+from atproto import Client
+from rich.console import Console
+
+from atpcli.config import Config
+from atpcli.display import display_post
+
+console = Console()
+
+atpcli_HEADER = r"""
+                  _  _
+  __ _ _ __  ____| (_)
+ / _` | '_ \/ ___| | |
+| (_| | |_) | (__| | |
+ \__,_| .__/ \___|_|_|
+      |_|
+""".strip("\n")
+
+
+@click.group()
+def cli():
+    """atpcli - A Python CLI wrapper around the atproto package."""
+    pass
+
+
+cli.help = textwrap.dedent(f"""\
+\b
+{atpcli_HEADER}
+
+🦋 atpcli - A Python CLI wrapper around the atproto package
+
+📚 GitHub: https://github.com/phalt/atpcli
+
+""").strip("\n")
+
+
+@click.group()
+def bsky():
+    """Commands for interacting with Bluesky."""
+    pass
+
+
+cli.add_command(bsky)
+
+
+@bsky.command()
+@click.option("--handle", prompt="Handle", help="Your Bluesky handle")
+@click.option("--password", prompt="Password", hide_input=True, help="Your Bluesky password")
+def login(handle: str, password: str):
+    """Login to Bluesky and save session."""
+    try:
+        client = Client()
+        console.print(f"[blue]Logging in as {handle}...[/blue]")
+        profile = client.login(handle, password)
+
+        # Get the session string from the client
+        session_string = client.export_session_string()
+
+        # Save the session
+        config = Config()
+        config.save_session(handle, session_string)
+
+        console.print(f"[green]✓ Successfully logged in as {profile.display_name or handle}[/green]")
+        console.print(f"[dim]Session saved to {config.config_file}[/dim]")
+    except Exception as e:
+        console.print(f"[red]✗ Login failed: {e}[/red]")
+        raise SystemExit(1)
+
+
+@bsky.command()
+@click.option("--limit", default=10, help="Number of posts to show")
+@click.option("--p", "page", default=1, help="Page number to load")
+def timeline(limit: int, page: int):
+    """View your timeline."""
+    config = Config()
+    handle, session_string = config.load_session()
+
+    if not session_string:
+        console.print("[red]✗ Not logged in. Please run 'atpcli bsky login' first.[/red]")
+        raise SystemExit(1)
+
+    try:
+        client = Client()
+        console.print(f"[blue]Loading timeline for {handle}...[/blue]")
+
+        # Restore session from saved string
+        client.login(session_string=session_string)
+
+        # Calculate cursor position for pagination
+        # Note: We need to fetch pages sequentially to get the cursor for each page.
+        # This means accessing page N requires N API calls, which can be slow for high page numbers.
+        cursor = None
+        if page > 5:
+            warning_msg = f"[yellow]⚠ Loading page {page} requires {page} API calls. This may take a moment...[/yellow]"
+            console.print(warning_msg)
+
+        for i in range(1, page):
+            response = client.get_timeline(limit=limit, cursor=cursor)
+            cursor = response.cursor
+            if not cursor:
+                console.print(f"[yellow]⚠ Page {page} does not exist. Showing last available page (page {i}).[/yellow]")
+                page = i
+                break
+
+        # Get the requested page
+        timeline_response = client.get_timeline(limit=limit, cursor=cursor)
+
+        # Reverse the feed so latest posts appear at the bottom
+        # This allows users to scroll up to read
+        reversed_feed = list(reversed(timeline_response.feed))
+
+        for feed_view in reversed_feed:
+            post = feed_view.post
+            table = display_post(post)
+            console.print(table)
+
+        # Show pagination info
+        page_info = f"[dim]Showing {len(timeline_response.feed)} posts (page {page})"
+        if timeline_response.cursor:
+            page_info += f" - Use --p {page + 1} for next page"
+        page_info += "[/dim]"
+        console.print(f"\n{page_info}")
+
+    except Exception as e:
+        console.print(f"[red]✗ Failed to load timeline: {e}[/red]")
+        console.print("[yellow]Your session may have expired. Try logging in again.[/yellow]")
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    cli()

atpcli-0.1.0/atpcli/config.py

@@ -0,0 +1,42 @@
+"""Configuration management for atpcli."""
+
+import json
+from pathlib import Path
+from typing import Optional
+
+
+class Config:
+    """Manage atpcli configuration and session state."""
+
+    def __init__(self, config_dir: Optional[Path] = None):
+        """Initialize config with optional custom directory."""
+        if config_dir is None:
+            config_dir = Path.home() / ".config" / "atpcli"
+        self.config_dir = config_dir
+        self.config_file = self.config_dir / "config.json"
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+
+    def save_session(self, handle: str, session_string: str) -> None:
+        """Save session information to config file."""
+        config_data = self.load_config()
+        config_data["handle"] = handle
+        config_data["session"] = session_string
+        with open(self.config_file, "w", encoding="utf-8") as f:
+            json.dump(config_data, f, indent=2)
+
+    def load_session(self) -> tuple[Optional[str], Optional[str]]:
+        """Load session information from config file."""
+        config_data = self.load_config()
+        return config_data.get("handle"), config_data.get("session")
+
+    def load_config(self) -> dict:
+        """Load the entire config file."""
+        if not self.config_file.exists():
+            return {}
+        with open(self.config_file, "r", encoding="utf-8") as f:
+            return json.load(f)
+
+    def clear_session(self) -> None:
+        """Clear the saved session."""
+        if self.config_file.exists():
+            self.config_file.unlink()