ebird-cli 0.1.0__py3-none-any.whl

ebird_cli/services/printing.py

@@ -0,0 +1,53 @@
+from rich.console import Console, Text
+from rich.table import Table
+
+from ..domain.fields import ExportFields
+from .dataframe import DataFrameService
+
+
+class PrintingService(DataFrameService):
+    def __init__(self, life_list: str | None, year_list: str | None, console: Console | None = None):
+        self.life_list = self.get_dataframe(life_list) if life_list else None
+        self.year_list = self.get_dataframe(year_list) if year_list else None
+        self.console = console or Console()
+
+    def print_observations(self, observations: list):
+        table = Table()
+
+        table.add_column("Date", style="magenta")
+        table.add_column("Observation")
+        table.add_column("Location")
+
+        regions = {obs.subname for obs in observations}
+        show_region = len(regions) > 1
+
+        if show_region:
+            table.add_column("Region")
+
+        for observation in observations:
+            row = (observation.observation_date, self.get_observation_text(observation), observation.location)
+            if show_region:
+                row += (observation.subname,)
+            table.add_row(*row)
+
+        print()
+        self.console.print(table)
+        print()
+        print(f"Total: {len(observations)}")
+
+    def get_observation_text(self, observation):
+        is_year_target = False
+        is_life_target = False
+        if self.year_list is not None:
+            is_year_target = not (self.year_list[ExportFields.common_name] == observation.name).any()
+        if self.life_list is not None:
+            is_life_target = not (self.life_list[ExportFields.common_name] == observation.name).any()
+
+        if is_life_target:
+            style = "red"
+        elif is_year_target:
+            style = "green"
+        else:
+            style = "white"
+
+        return Text(observation.name, style)

ebird_cli/services/taxonomy.py

@@ -0,0 +1,18 @@
+from ..domain.fields import EbirdFields
+from ..domain.taxonomy_cache import TaxonomyCache
+from .dataframe import DataFrameService
+
+
+class TaxonomyService(DataFrameService):
+    def __init__(self, taxonomy_cache: TaxonomyCache):
+        self.taxonomy_cache = taxonomy_cache
+
+    def search_by_common_name(self, name: str) -> list[str]:
+        df = self.taxonomy_cache.national
+        matches = df[df[EbirdFields.common_name].str.contains(name, na=False, case=False)]
+        return matches[EbirdFields.common_name].to_list()
+
+    def get_species_code(self, common_name: str) -> list[str]:
+        df = self.taxonomy_cache.national
+        matches = df[df[EbirdFields.common_name] == common_name]
+        return matches[EbirdFields.species_code].to_list()

ebird_cli/utils/logger.py

@@ -0,0 +1,17 @@
+import logging
+import os
+
+from appdirs import user_log_dir
+
+logger = logging.getLogger("ebird_cli_logger")
+
+
+def configure_logging(log_dir: str | None = None):
+    """Append the app log to app.log in log_dir, the user log directory by default. Called at launch, not import."""
+    log_dir = log_dir or user_log_dir("ebird_cli")
+    os.makedirs(log_dir, exist_ok=True)
+
+    handler = logging.FileHandler(os.path.join(log_dir, "app.log"), mode="a", encoding="utf-8")
+    handler.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s"))
+    logger.addHandler(handler)
+    logger.setLevel(logging.DEBUG)

ebird_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: ebird-cli
+Version: 0.1.0
+Summary: A command-line interface for exploring eBird bird observation data.
+Author-email: Kevin Verreault <dev@kevinverreault.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kevinverreault/ebird-cli
+Project-URL: Repository, https://github.com/kevinverreault/ebird-cli
+Project-URL: Issues, https://github.com/kevinverreault/ebird-cli/issues
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: appdirs>=1.4.4
+Requires-Dist: certifi>=2024.8.30
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: ebird-api<4,>=3.0.6
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: prompt_toolkit>=3.0.48
+Requires-Dist: requests>=2.32.3
+Requires-Dist: rich>=13.9.4
+Dynamic: license-file
+
+# eBird CLI
+
+A command-line interface for exploring eBird bird observation data.
+
+![Notable observations in a region, with life and year list targets highlighted](https://raw.githubusercontent.com/kevinverreault/ebird-cli/main/docs/demo/overview.gif)
+
+## Prerequisites
+
+- Python 3.11+
+- eBird API Key (obtainable with free eBird account)
+
+## Installation
+
+1. Clone the repository
+2. Set up a virtual environment
+3. Install the `ebird-cli` command from the checkout:
+   ```bash
+   pip install .
+   ```
+4. Configure your eBird API key
+
+## Configuration
+
+### Command-Line Arguments
+
+The CLI supports the following arguments:
+
+| Argument         | Description                           | Default                           | Required |
+| ---------------- | ------------------------------------- | --------------------------------- | -------- |
+| `--api-key`      | eBird API key                         | From `EBIRDAPIKEY` env var        | **Yes**  |
+| `--region`       | eBird subnational level 2 region code | From `EBIRDDEFAULTREGION` env var | **Yes**  |
+| `--locale`       | Language locale                       | From `EBIRDLOCALE` (or `fr`)      | No       |
+| `--lat`          | Latitude                              | From `EBIRDLAT` env var           | No       |
+| `--long`         | Longitude                             | From `EBIRDLONG` env var          | No       |
+| `--year-list`    | Path to year observations list        | From `EBIRDYEARLIST` env var      | No       |
+| `--life-list`    | Path to lifetime observations list    | From `EBIRDLIFELIST` env var      | No       |
+| `--aggregations` | Path to aggregations JSON file        | From `EBIRDAGGREGATIONS` env var  | No       |
+
+### Environment Variables
+
+You can configure the CLI using the following environment variables to avoid manual parameter entry:
+
+- `EBIRDAPIKEY`: Your eBird API key
+- `EBIRDDEFAULTREGION`: Default region for default search and hotspots filtering (`CA-QC-MR`)
+- `EBIRDLOCALE`: Preferred language locale (`fr`)
+- `EBIRDLAT`: Latitude for location-based searches (`47.87`)
+- `EBIRDLONG`: Longitude for location-based searches (`-72.17`)
+- `EBIRDYEARLIST`: Path to your year observations list (`~/ebird_data/year_list.csv`)
+- `EBIRDLIFELIST`: Path to your lifetime observations list (`~/ebird_data/life_list.csv`)
+- `EBIRDAGGREGATIONS`: Path to your aggregations JSON file (`~/ebird_data/aggregations.json`)
+
+## Usage
+
+### Launching the CLI
+
+```bash
+ebird-cli --api-key <ebird-api-key> --region <region-code> [optional arguments]
+```
+
+`ebird-cli --version` prints the installed version.
+
+### Available Commands
+
+When launched, the CLI will display a menu of available commands:
+
+- `recent <scope, -region> [-back, -species]`: Fetch recent bird observations
+- `notable <scope, -region> [-back]`: Fetch notable bird observations
+
+### Autocompletion
+
+Suggestions appear as you type: command names, scopes, flags, region names for the chosen scope, species names and `-back` values. Press Tab to accept the first suggestion, or press it again to cycle through them.
+
+![Building a full command from autocompletion suggestions](https://raw.githubusercontent.com/kevinverreault/ebird-cli/main/docs/demo/autocomplete.gif)
+
+### Search Scopes
+
+Bird observations can be searched in multiple scopes.
+
+1. **Nearby**: Based on provided latitude and longitude
+   - Requires `--lat` and `--long` program arguments
+   - Shows observations near the specified geographic coordinates
+   - `recent nearby`
+
+2. **Hotspot**: eBird-defined hotspots
+   - `recent hotspot -region Dunes de Tadoussac`
+
+3. **Regional**: eBird Subnational Level 2
+   - `recent regional -region Montréal`
+
+4. **Subnational**: eBird Subnational Level 1
+   - `recent subnational -region Québec`
+
+The `-region` flag supports context-sensitive autocompletion based on the selected scope. If no `-region` flag is provided, default region will be used.
+
+![Autocompleting a hotspot name and fetching its recent observations](https://raw.githubusercontent.com/kevinverreault/ebird-cli/main/docs/demo/hotspot-autocomplete.gif)
+
+### Search length
+
+Use the optional `-back` parameter to change the number of days back to fetch observations.
+
+- Values: from 1 to 30
+- Default: 7
+
+  ```
+  notable subnational -region Québec -back 30
+  ```
+
+### Aggregations
+
+Aggregations allow you to define custom named groups of hotspots that appear alongside eBird hotspots when using the `hotspot` scope. This is useful for combining multiple nearby locations under a single name.
+
+Provide the path to your aggregations file via `--aggregations` or the `EBIRDAGGREGATIONS` environment variable:
+
+```bash
+ebird-cli --api-key <key> --region <region> --aggregations ~/ebird_data/aggregations.json
+```
+
+The aggregations file is a JSON array where each element maps a custom name to a list of eBird location IDs:
+
+```json
+[
+  {
+    "Technoparc": ["L9980102", "L4886900", "L11363355"]
+  }
+]
+```
+
+Once configured, aggregation names are available in the `-region` autocomplete when using the `hotspot` scope:
+
+```
+recent hotspot -region Technoparc
+```
+
+### Species filter
+
+Use the optional `-species` flag with the `recent` command to filter observations to a single species.
+
+```
+recent nearby -species Canard colvert
+recent regional -region Montréal -species Harfang des neiges
+```
+
+The `-species` flag supports context-sensitive autocompletion using the cached taxonomy. Start typing a common name and press Tab to see matching species.
+
+![Autocompleting a species name and filtering recent observations to it](https://raw.githubusercontent.com/kevinverreault/ebird-cli/main/docs/demo/species-filter.gif)
+
+> **Note:** Autocompletion and lookup use the locale specified by `--locale` / `EBIRDLOCALE`. Species names must be typed in the configured locale.
+
+### List highlighting
+
+When using `--year-list` and `--life-list`:
+
+- Year list targets are highlighted in **green**
+- Life list targets are highlighted in **red**
+
+### Obtaining list files
+
+The eBird API does not expose life list or year list data, so these CSV files must be downloaded from the eBird website. The `ebird-cli-download-lists` command, installed alongside `ebird-cli`, downloads both into `output_dir` as `life_list.csv` and `year_list.csv`:
+
+```bash
+ebird-cli-download-lists session_id output_dir
+```
+
+This requires a valid eBird session cookie (`EBIRD_SESSIONID`), which can be obtained from your browser after logging in to ebird.org. The command must be re-run whenever your lists change.
+
+> **Note:** The life list only changes when you see a species for the first time ever, making it infrequent and easy to manage. The year list changes with every new species seen in the current year and resets annually, requiring more frequent re-runs of the command.
+
+## Data cache
+
+To avoid redundant API calls to eBird, the CLI caches reference data locally on first run. The cache is stored in the platform-appropriate user cache directory (e.g. `%LOCALAPPDATA%\ebird_cli\Cache\ebird_cli` on Windows, `~/.cache/ebird_cli` on Linux/macOS).
+
+The following data is cached:
+
+- **Location data** (per region): subnational level 1 regions, subnational level 2 regions, and every hotspot in the subnational region — stored as JSON files under `location/<national>/` and `location/<national>/<subnational>/`
+- **Taxonomy** (per locale and national region): the full eBird taxonomy filtered to species observed in the configured country — stored as CSV files under `taxonomy/<national>/`
+
+Hotspots are fetched again on launch once their cached file is more than 30 days old, so new hotspots appear; if eBird can't be reached, the older file is used. All other cached data is written once and reused on every subsequent launch. To force a refresh (e.g. after a new eBird taxonomy release or a region change), delete the relevant files or the entire cache directory.
+
+## Log file
+
+Each launch appends debug messages to `app.log` in the platform-appropriate user log directory, created on first launch:
+
+- Windows: `%LOCALAPPDATA%\ebird_cli\ebird_cli\Logs\app.log`
+- Linux: `~/.cache/ebird_cli/log/app.log` (under `$XDG_CACHE_HOME` instead of `~/.cache` when it is set)
+- macOS: `~/Library/Logs/ebird_cli/app.log`
+
+The file is never rotated or trimmed; delete it at any time.
+
+## Development setup
+
+### Virtual environment
+
+1. Activate the virtual environment:
+   - On Windows: `venv\Scripts\activate`
+   - On macOS/Linux: `source venv/bin/activate`
+
+2. Install the project in editable mode with the dev tools (`requirements-dev.txt` adds the test, lint and build tools to the pinned runtime dependencies):
+   ```bash
+   pip install -e . -r requirements-dev.txt
+   ```
+   The tests read the version from the installed package, so they need this editable install.
+
+### Tests
+
+The test suite runs offline: it never calls the eBird API, needs no API key and never touches your user cache or log directory.
+
+```bash
+python -m pytest
+```
+
+Tests live in `tests/`, mirroring the source layout:
+
+- `tests/cli/`: the `recent` and `notable` commands and autocompletion, driven through their public entry points
+- `tests/services/`, `tests/domain/`: cache, location and taxonomy services and domain value parsing
+- `tests/utils/`: where the app log is written
+- `tests/test_prompt_dispatch.py`, `tests/test_program_arguments.py`: prompt input handling and program arguments
+- `tests/conftest.py`: shared fixtures, including `make_cli`, which wires real services and commands the way `main` does
+- `tests/fakes.py`: the in-memory fake eBird client, the only test double
+- `tests/fixtures/`: small hand-written cache, list and aggregation files for the `CA-QC-MR` region
+
+Tests named `..._currently_...` pin behaviour that looks accidental, so changing it is a deliberate test change.
+
+### Demo GIFs
+
+The GIFs in this README are recorded with [VHS](https://github.com/charmbracelet/vhs) from the tapes in `docs/demo/`. They call the live eBird API, so they need your API key and environment variables set. `config.tape` holds the shared settings and launches the CLI out of frame.
+
+On Windows, install VHS and its terminal dependency, then re-record a GIF from the repository root:
+
+```bash
+winget install charmbracelet.vhs tsl0922.ttyd
+```
+
+```bash
+vhs docs/demo/overview.tape
+```
+
+VHS also needs `ffmpeg` on the `PATH`.
+
+### Cutting a release
+
+Releases are published to [PyPI](https://pypi.org/project/ebird-cli/) by the `Release` workflow (`.github/workflows/release.yml`) through trusted publishing; no API token is involved.
+
+1. Bump `version` in `pyproject.toml` and merge it to `main`.
+2. Optionally, do a dry run: run the `Release` workflow manually from the Actions tab. It uploads that version to [TestPyPI](https://test.pypi.org/project/ebird-cli/), which accepts each version only once. Check the upload installs:
+   ```bash
+   pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ ebird-cli
+   ```
+3. Tag the release commit `vX.Y.Z`, matching the version, and push the tag.
+4. Publish a GitHub release from that tag. The workflow uploads it to PyPI, and fails without uploading if the tag doesn't match the version in `pyproject.toml`.
+
+## Credits
+
+Bird observation data and the eBird platform are provided by the [Cornell Lab of Ornithology](https://www.birds.cornell.edu/). This project would not be possible without their freely available [eBird API](https://documenter.getpostman.com/view/664302/S1ENwy59).
+
+This project relies on the following open-source packages:
+
+- [ebird-api](https://pypi.org/project/ebird-api/) — Python wrapper for the eBird API
+- [prompt_toolkit](https://python-prompt-toolkit.readthedocs.io/) — Interactive command-line interface with autocompletion
+- [rich](https://rich.readthedocs.io/) — Terminal formatting and highlighted output
+- [pandas](https://pandas.pydata.org/) — CSV observation list parsing
+- [colorama](https://pypi.org/project/colorama/) — Cross-platform terminal color support
+- [requests](https://requests.readthedocs.io/) — HTTP requests to the eBird API
+
+## License
+
+MIT License

ebird_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+ebird_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ebird_cli/download_lists.py,sha256=y8jwB_fQuX11qEbJI_zovixpo7E1gqmD5p6tquT_PFc,1483
+ebird_cli/main.py,sha256=gBexi6LuOg3Z9Cr42GU39xtx1JG3ZvrYGpBt9MMO2nk,7579
+ebird_cli/cli/__init__.py,sha256=xF6fPmoFZiml3nqhp0hnPSHRP2rfzU-_Xwvf98LYx70,93
+ebird_cli/cli/autocomplete.py,sha256=XH8li6n2aGlclMsDHCiEgfXZrkZ7XSq8NRIWxM7LJD4,1347
+ebird_cli/cli/command.py,sha256=IK-ffeoh8lv6wSPfxuSxepDrxnWuq9pWVuUy3QL6k7s,5222
+ebird_cli/cli/grammar.py,sha256=z7Ojn3KbsF6IQwdMDUdy3axsaFMbn-604SjtOQeOyrA,8651
+ebird_cli/domain/__init__.py,sha256=6AIrDtfl4WUbt_U2YPaciHMTP3ulaJWmjkdrNqUK9Lc,117
+ebird_cli/domain/fields.py,sha256=1pLEevMh018EJjLfCf2CTGg5qCLnYIbKcS8jeI4LKNo,511
+ebird_cli/domain/observation.py,sha256=FMCIXtWuNYlPlvHNVpj44ZqblYTIOKYEmI_TKi6OqQQ,888
+ebird_cli/domain/region.py,sha256=USBvw32l5ArHZDualiVim1B7fe682tMI2rtXC8xjX54,259
+ebird_cli/domain/regional_scopes.py,sha256=PrDvlZc4ddktgSUKhVU5WxSG5NzeBTStLUhdcAVvLHg,190
+ebird_cli/domain/taxonomy.py,sha256=1vqP2180Jd-JM3DRCYEybcbPPMQ--jYJWBFt3ikuy0U,1205
+ebird_cli/domain/taxonomy_cache.py,sha256=Xbd9INoG5t3vVmhgl3NclB-bNEcLKpcfP-nY3cxUhAY,243
+ebird_cli/services/__init__.py,sha256=oYVplQ4V-vP152GqJK3X4EkkBgwN4lG1p2mP2qD00Pc,140
+ebird_cli/services/cache.py,sha256=IjD-suVGXrwSbYN162TrG_aLJ8qOz59ClfGuJi1HPeU,2059
+ebird_cli/services/dataframe.py,sha256=QtWxRRbD6r8HYIYXLw1EG9pnTwpP8MoJGVtY7NmMh3Y,398
+ebird_cli/services/ebird_client.py,sha256=8f0z2-S9wWOxrZh6kzAjP52-ffcNu2hXSLUBrFGMJ1A,3938
+ebird_cli/services/location_catalogue.py,sha256=-wqK8DsNxwH3wa5hCwCUPO58Pe5OBv-R4jRqz5sU2yU,5427
+ebird_cli/services/observation_query.py,sha256=snflAlQLU0qU9FFNBZDzJRwadgLxHVdiw25MsigY3-M,4700
+ebird_cli/services/printing.py,sha256=zTmmtTvnV4R4Zfm6rNDgSmsqezfrW10X4QFgLOQh1iM,1826
+ebird_cli/services/taxonomy.py,sha256=VA0QtSAzcCGnb2kDGXa2dsrY1hbNE1WPFeiL627ey-A,756
+ebird_cli/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ebird_cli/utils/logger.py,sha256=G-5coWujFFLJ2JVka6yQo64HUkzhlJM2u_9RKipEzvo,631
+ebird_cli-0.1.0.dist-info/licenses/LICENSE,sha256=G4LcioAWXb-vOlvz13XmGXiWpAWknuxhew4L0qhzefU,1072
+ebird_cli-0.1.0.dist-info/METADATA,sha256=6uFCV4MOtRfSGfGZPP31wJKTPuX5qGiC8Q3h_LlcV4s,13039
+ebird_cli-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ebird_cli-0.1.0.dist-info/entry_points.txt,sha256=HsU_eP6Ep-yBTmLx6SbGV_XYECfj53imIlcuPMdgPgw,107
+ebird_cli-0.1.0.dist-info/top_level.txt,sha256=aqJzk6etMmpZKSXEjjuNX0LTsahNT3sAJkUuUoSHQ6E,10
+ebird_cli-0.1.0.dist-info/RECORD,,

ebird_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ebird_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ebird-cli = ebird_cli.main:main
+ebird-cli-download-lists = ebird_cli.download_lists:main

ebird_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kevin Verreault
+
+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.

ebird_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ebird_cli