ebird-cli 0.1.0__py3-none-any.whl

ebird_cli/main.py

@@ -0,0 +1,252 @@
+import argparse
+import os
+import re
+import ssl
+import urllib.request
+from importlib.metadata import version
+
+import certifi
+from appdirs import user_cache_dir
+from colorama import Fore
+from prompt_toolkit import PromptSession
+from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.keys import Keys
+from prompt_toolkit.styles import Style
+
+from .cli.autocomplete import ContextSensitiveCompleter
+from .cli.command import NotableCommand, RecentCommand
+from .cli.grammar import CommandLineError
+from .domain.region import Region
+from .services.cache import CacheService
+from .services.ebird_client import EbirdClient
+from .services.location_catalogue import LocationCatalogue
+from .services.observation_query import ObservationQuery
+from .services.printing import PrintingService
+from .services.taxonomy import TaxonomyService
+from .utils.logger import configure_logging
+
+api_key_env_variable = "EBIRDAPIKEY"
+locale_env_variable = "EBIRDLOCALE"
+default_region_env_variable = "EBIRDDEFAULTREGION"
+year_list_env_variable = "EBIRDYEARLIST"
+life_list_env_variable = "EBIRDLIFELIST"
+lat_env_variable = "EBIRDLAT"
+long_env_variable = "EBIRDLONG"
+aggregations_env_variable = "EBIRDAGGREGATIONS"
+
+region_regex = "([A-Z]{2}-){2}[A-Z]{2}"
+
+
+def regex_type(pattern: str | re.Pattern):
+    def closure_check_regex(arg_value):
+        if not re.match(pattern, arg_value):
+            raise argparse.ArgumentTypeError("invalid value")
+        return arg_value
+
+    return closure_check_regex
+
+
+def print_menu(commands, args=None):
+    examples = []
+
+    for value in commands.values():
+        examples.append(value.command_example())
+    formatted_examples = "\n    ".join(f"{item}" for item in examples)
+
+    args_section = ""
+    if args is not None:
+        arg_lines = [
+            f"{Fore.BLUE}region{Fore.RESET}: {args.region}",
+            f"{Fore.BLUE}locale{Fore.RESET}: {args.locale}",
+        ]
+        args_section = "\n    Arguments:\n    \n    " + "\n    ".join(arg_lines) + "\n    "
+
+    menu = f"""
+    {Fore.GREEN}eBird CLI{Fore.RESET}
+    {args_section}
+    Available commands:
+
+    {formatted_examples}
+    """
+
+    print(menu)
+
+
+def setup_key_bindings():
+    bindings = KeyBindings()
+
+    @bindings.add(Keys.Tab)
+    def handle_tab(event):
+        buffer = event.app.current_buffer
+        if buffer.complete_state:
+            buffer.complete_next()
+        else:
+            buffer.start_completion(select_first=True)
+
+    return bindings
+
+
+def use_certifi_ca_bundle():
+    # ebird-api calls urllib's urlopen, which on Windows only trusts roots already in the Windows store.
+    # Windows downloads roots on demand, so eBird's root may be missing; use certifi's bundle like requests does.
+    context = ssl.create_default_context(cafile=certifi.where())
+    urllib.request.install_opener(urllib.request.build_opener(urllib.request.HTTPSHandler(context=context)))
+
+
+def setup_parser(parser: argparse.ArgumentParser):
+    parser.add_argument("--version", action="version", version=f"ebird-cli {version('ebird-cli')}")
+
+    parser.add_argument(
+        "--api-key",
+        default=os.getenv(api_key_env_variable),
+        required=os.getenv(api_key_env_variable) is None,
+        help=f"eBird API key (mandatory if {api_key_env_variable} env variable is not set)",
+    )
+
+    parser.add_argument(
+        "--region",
+        default=os.getenv(default_region_env_variable),
+        required=os.getenv(default_region_env_variable) is None,
+        help=(
+            "eBird subnational level 2 region code is mandatory if "
+            f"{default_region_env_variable} env variable is not set"
+        ),
+        type=regex_type(region_regex),
+    )
+
+    parser.add_argument(
+        "--locale",
+        type=str,
+        default=os.getenv(locale_env_variable) if os.getenv(locale_env_variable) is not None else "fr",
+        help="Locale",
+    )
+
+    parser.add_argument(
+        "--lat",
+        type=str,
+        default=os.getenv(lat_env_variable),
+        help="Latitude",
+    )
+
+    parser.add_argument(
+        "--long",
+        type=str,
+        default=os.getenv(long_env_variable),
+        help="Longitude",
+    )
+
+    parser.add_argument(
+        "--year-list",
+        type=str,
+        default=os.getenv(year_list_env_variable),
+        help="List of observations for the current year",
+    )
+
+    parser.add_argument(
+        "--life-list",
+        type=str,
+        default=os.getenv(life_list_env_variable),
+        help="List of lifetime observations",
+    )
+
+    parser.add_argument(
+        "--aggregations",
+        type=str,
+        default=os.getenv(aggregations_env_variable),
+        help=f"Path to aggregations JSON file (custom hotspot groups). From {aggregations_env_variable} env var",
+    )
+
+
+def main():
+    configure_logging()
+
+    parser = argparse.ArgumentParser(description="eBird CLI")
+    setup_parser(parser)
+
+    args = parser.parse_args()
+
+    api_key = args.api_key
+    region = args.region
+    locale = args.locale
+    lat = args.lat
+    long = args.long
+
+    life_list = args.life_list or None
+    year_list = args.year_list or None
+    aggregations = args.aggregations or None
+
+    use_certifi_ca_bundle()
+
+    client = EbirdClient(api_key, locale)
+    cache_dir = user_cache_dir("ebird_cli")
+
+    cache_service = CacheService(api_key, locale, Region(region), api_client=client, cache_dir=cache_dir)
+    printing_service = PrintingService(life_list, year_list)
+    location_catalogue = LocationCatalogue.load(Region(region), client, cache_dir, aggregations)
+    observation_query = ObservationQuery(client, location_catalogue, lat, long)
+    taxonomy_service = TaxonomyService(cache_service.taxonomy_cache)
+
+    commands = {
+        command.command_name: command
+        for command in [
+            RecentCommand(observation_query, location_catalogue, printing_service, taxonomy_service),
+            NotableCommand(observation_query, location_catalogue, printing_service),
+        ]
+    }
+
+    style = Style.from_dict(
+        {
+            "prompt": "ansigreen bold",
+            "": "ansiwhite",
+            "completion-menu.completion": "bg:#008888 #ffffff",
+            "completion-menu.completion.current": "bg:#00aaaa #000000",
+        }
+    )
+
+    print_menu(commands, args)
+    session = PromptSession(completer=ContextSensitiveCompleter(commands.values()), key_bindings=setup_key_bindings())
+
+    while True:
+        try:
+            print("")
+            user_input = session.prompt("⋙  ", style=style)
+            if not handle_input(user_input, commands, args):
+                break
+        except KeyboardInterrupt:
+            continue
+        except EOFError:
+            break
+
+
+def handle_input(user_input: str, commands, program_args) -> bool:
+    """Run one line typed at the prompt. Returns whether the session should continue."""
+    try:
+        if user_input.lower() == "exit" or user_input.lower() == "e":
+            print("Exiting eBird CLI.")
+            return False
+
+        if user_input == "":
+            print_menu(commands, program_args)
+            return True
+
+        words = user_input.split()
+        if not words:
+            return True
+
+        command_name, *command_args = words
+        user_request = commands.get(command_name)
+
+        if user_request:
+            user_request.handle_command(*command_args)
+        else:
+            print("Unknown command.")
+    except CommandLineError as e:
+        print(f"Invalid argument: {e.message}")
+    except Exception as e:
+        print(f"An error occurred: {e}")
+
+    return True
+
+
+if __name__ == "__main__":
+    main()

ebird_cli/services/__init__.py

@@ -0,0 +1,4 @@
+from .location_catalogue import LocationCatalogue
+from .taxonomy import TaxonomyService
+
+__all__ = ["LocationCatalogue", "TaxonomyService"]

ebird_cli/services/cache.py

@@ -0,0 +1,55 @@
+import csv
+import os
+
+import pandas as pd
+from appdirs import user_cache_dir
+
+from ..domain.fields import EbirdFields
+from ..domain.region import Region
+from ..domain.taxonomy_cache import TaxonomyCache
+from .ebird_client import EbirdClient
+
+TAXONOMY_DIR = "taxonomy"
+
+
+def write_csv(file_path, data):
+    with open(file_path, mode="w", newline="", encoding="utf-8") as csvfile:
+        fieldnames = list(dict.fromkeys(k for row in data for k in row))
+        writer = csv.DictWriter(
+            csvfile,
+            fieldnames=fieldnames,
+            quoting=csv.QUOTE_MINIMAL,
+            extrasaction="ignore",
+        )
+
+        writer.writeheader()
+        writer.writerows(data)
+
+
+class CacheService:
+    def __init__(self, api_key: str, locale: str, region: Region, api_client=None, cache_dir: str | None = None):
+        self.api_client = api_client or EbirdClient(api_key, locale)
+        self.cache_dir = cache_dir or user_cache_dir("ebird_cli")
+
+        national_taxonomy_path = self.get_taxonomy(region)
+
+        self.taxonomy_cache = TaxonomyCache(region, national_taxonomy_path)
+
+    def get_taxonomy(self, region: Region) -> str:
+        taxonomy_path = os.path.join(self.cache_dir, TAXONOMY_DIR, "taxonomy.csv")
+        national_taxonomy_path = os.path.join(self.cache_dir, TAXONOMY_DIR, region.national, "taxonomy.csv")
+
+        if not os.path.exists(taxonomy_path):
+            taxonomy = self.api_client.get_ebird_taxonomy()
+            os.makedirs(os.path.dirname(taxonomy_path), exist_ok=True)
+            write_csv(taxonomy_path, taxonomy)
+
+        taxonomy_df = pd.read_csv(taxonomy_path)
+
+        if not os.path.exists(national_taxonomy_path):
+            national_species = self.api_client.get_national_species(region.national)
+            national_taxonomy_df = taxonomy_df[taxonomy_df[EbirdFields.species_code].isin(national_species)]
+            os.makedirs(os.path.dirname(national_taxonomy_path), exist_ok=True)
+            national_taxonomy_df.to_csv(national_taxonomy_path, index=False)
+
+        return national_taxonomy_path

ebird_cli/services/dataframe.py

@@ -0,0 +1,14 @@
+import pandas
+
+from ..domain.fields import ExportFields
+
+
+class DataFrameService:
+    def is_csv(self, filename) -> bool:
+        return filename[-3:] == "csv"
+
+    def get_dataframe(self, filepath) -> pandas.DataFrame:
+        if filepath and self.is_csv(filepath):
+            return pandas.read_csv(filepath)
+        else:
+            return pandas.DataFrame(columns=[ExportFields.common_name])

ebird_cli/services/ebird_client.py

@@ -0,0 +1,111 @@
+import requests
+from ebird.api import Client, constants, observations
+
+
+class EbirdClient(Client):
+    """The ebird-api client plus the reference endpoints it doesn't wrap the way the CLI calls them.
+
+    Client reads `back` and `hotspot` from its own attributes; the observation methods here take them
+    per call instead, so callers never have to change the client's state before a request.
+    """
+
+    def __init__(self, api_key: str, locale: str):
+        super().__init__(api_key, locale)
+        self.detail = "full"
+        # Client.locale holds the validated form; the taxonomy endpoint has always been sent the locale as given.
+        self.taxonomy_locale = locale
+
+    def get_observations(self, area, back=constants.DEFAULT_BACK, hotspot=False):
+        return observations.get_observations(
+            self.api_key,
+            area,
+            back=back,
+            max_results=self.max_observations,
+            locale=self.locale,
+            provisional=self.provisional,
+            hotspot=hotspot,
+            detail=self.detail,
+            category=self.category,
+        )
+
+    def get_notable_observations(self, area, back=constants.DEFAULT_BACK, hotspot=False):
+        return observations.get_notable_observations(
+            self.api_key,
+            area,
+            back=back,
+            max_results=self.max_observations,
+            locale=self.locale,
+            hotspot=hotspot,
+            detail=self.detail,
+        )
+
+    def get_species_observations(self, species, area, back=constants.DEFAULT_BACK, hotspot=False):
+        return observations.get_species_observations(
+            self.api_key,
+            species,
+            area,
+            back=back,
+            max_results=self.max_observations,
+            locale=self.locale,
+            provisional=self.provisional,
+            hotspot=hotspot,
+            detail=self.detail,
+            category=self.category,
+        )
+
+    def get_nearby_observations(self, lat, lng, dist=25, back=constants.DEFAULT_BACK, hotspot=False):
+        return observations.get_nearby_observations(
+            self.api_key,
+            lat,
+            lng,
+            dist=dist,
+            back=back,
+            max_results=self.max_observations,
+            locale=self.locale,
+            provisional=self.provisional,
+            hotspot=hotspot,
+            category=self.category,
+        )
+
+    def get_nearby_notable(self, lat, lng, dist=25, back=constants.DEFAULT_BACK, hotspot=False):
+        return observations.get_nearby_notable(
+            self.api_key,
+            lat,
+            lng,
+            dist=dist,
+            back=back,
+            max_results=self.max_observations,
+            locale=self.locale,
+            hotspot=hotspot,
+            detail=self.detail,
+        )
+
+    def get_nearby_species(self, species, lat, lng, dist=25, back=constants.DEFAULT_BACK, hotspot=False):
+        return observations.get_nearby_species(
+            self.api_key,
+            species,
+            lat,
+            lng,
+            dist=dist,
+            back=back,
+            max_results=self.max_observations,
+            locale=self.locale,
+            provisional=self.provisional,
+            hotspot=hotspot,
+            category=self.category,
+        )
+
+    def get_ebird_taxonomy(self) -> list[dict]:
+        url = "https://api.ebird.org/v2/ref/taxonomy/ebird"
+        headers = {"X-eBirdApiToken": self.api_key}
+        params = {"fmt": "json", "locale": self.taxonomy_locale}
+        response = requests.get(url, headers=headers, params=params)
+        response.raise_for_status()
+        return response.json()
+
+    def get_national_species(self, country: str) -> list[str]:
+        url = f"https://api.ebird.org/v2/product/spplist/{country}"
+        headers = {"X-eBirdApiToken": self.api_key}
+        response = requests.get(url, headers=headers)
+        response.raise_for_status()
+        return response.json()

ebird_cli/services/location_catalogue.py

@@ -0,0 +1,121 @@
+import json
+import os
+import time
+from collections.abc import Callable
+from datetime import timedelta
+from urllib.error import HTTPError
+
+from ..domain.fields import EbirdFields
+from ..domain.region import Region
+from ..domain.regional_scopes import RegionalScopes
+
+LOCATION_DIR = "location"
+# Hotspots are created all the time; Regions practically never change, so their files don't expire.
+HOTSPOTS_MAX_AGE = timedelta(days=30)
+
+
+def is_fresh(file_path: str, max_age: timedelta | None) -> bool:
+    """Whether the file exists and, given a max age, was written no longer ago than that."""
+    if not os.path.exists(file_path):
+        return False
+    return max_age is None or time.time() - os.path.getmtime(file_path) <= max_age.total_seconds()
+
+
+def cached(file_path: str, fetch: Callable[[], list[dict]], max_age: timedelta | None = None) -> list[dict]:
+    """The eBird response cached at file_path, fetched and stored verbatim first if it isn't there or is too old.
+
+    A file that is too old is still used when eBird can't be reached, but not when eBird refuses the request.
+    """
+    if not is_fresh(file_path, max_age):
+        try:
+            response = fetch()
+        except HTTPError:
+            raise
+        except OSError:  # URLError and timeouts both derive from it
+            if not os.path.exists(file_path):
+                raise
+        else:
+            os.makedirs(os.path.dirname(file_path), exist_ok=True)
+            # Write beside the file and swap it in, so an interrupted write can't leave a broken cache behind.
+            partial_path = file_path + ".partial"
+            with open(partial_path, "w", encoding="utf-8") as file:
+                json.dump(response, file, ensure_ascii=False, indent=2)
+            os.replace(partial_path, file_path)
+    with open(file_path, encoding="utf-8") as file:
+        return json.load(file)
+
+
+def read_aggregations(aggregations_path: str | None) -> dict[str, list[str]]:
+    """Aggregation name to Hotspot ids, merged from every object in the file; a missing file means none."""
+    if not aggregations_path:
+        return {}
+    file_path = os.path.expanduser(aggregations_path)
+    if not os.path.isfile(file_path):
+        return {}
+    with open(file_path, encoding="utf-8") as file:
+        aggregations = {}
+        for aggregation in json.load(file):
+            aggregations.update(aggregation)
+        return aggregations
+
+
+class LocationCatalogue:
+    """Every Location the user can name around their Home Region, by Regional scope."""
+
+    def __init__(
+        self,
+        home_region: Region,
+        subnationals: list[dict],
+        regionals: list[dict],
+        hotspots: list[dict],
+        aggregations: dict[str, list[str]],
+    ):
+        self.home_codes = {
+            RegionalScopes.SUBNATIONAL: home_region.subnational,
+            RegionalScopes.REGIONAL: home_region.regional,
+            RegionalScopes.HOTSPOT: home_region.regional,
+        }
+        self.locations: dict[RegionalScopes, list[tuple[str, list[str]]]] = {
+            RegionalScopes.SUBNATIONAL: [(row[EbirdFields.name], [row[EbirdFields.code]]) for row in subnationals],
+            RegionalScopes.REGIONAL: [(row[EbirdFields.name], [row[EbirdFields.code]]) for row in regionals],
+            RegionalScopes.HOTSPOT: [
+                *((row[EbirdFields.location_name], [row[EbirdFields.location_id]]) for row in hotspots),
+                *aggregations.items(),
+            ],
+        }
+
+    @classmethod
+    def load(cls, home_region: Region, client, cache_dir: str, aggregations_path: str | None = None):
+        """Read the Home Region's Locations from the cache, fetching them from eBird when missing."""
+        national_dir = os.path.join(cache_dir, LOCATION_DIR, home_region.national)
+        subnational_dir = os.path.join(national_dir, home_region.subnational)
+        return cls(
+            home_region,
+            cached(
+                os.path.join(national_dir, "subnationals.json"),
+                lambda: client.get_regions("subnational1", home_region.national),
+            ),
+            cached(
+                os.path.join(subnational_dir, "regionals.json"),
+                lambda: client.get_regions("subnational2", home_region.subnational),
+            ),
+            cached(
+                os.path.join(subnational_dir, "hotspots.json"),
+                # Without back, eBird returns every Hotspot in the Region, not only the recently visited ones.
+                lambda: client.get_hotspots(home_region.subnational, back=None),
+                HOTSPOTS_MAX_AGE,
+            ),
+            read_aggregations(aggregations_path),
+        )
+
+    def names(self, scope: RegionalScopes, query: str = "") -> list[str]:
+        """Names of the scope's Locations containing the query, ignoring case; nearby has none."""
+        return [name for name, _ in self.locations.get(scope, []) if query.lower() in name.lower()]
+
+    def resolve(self, scope: RegionalScopes, name: str | None = None) -> list[str]:
+        """Location ids of the scope's Locations with exactly this name; no name means the Home Region at that scope."""
+        if scope not in self.locations:
+            raise ValueError(f"{scope} is not a scope of named Locations")
+        if name is None:
+            return [self.home_codes[scope]]
+        return [location_id for candidate, ids in self.locations[scope] if candidate == name for location_id in ids]

ebird_cli/services/observation_query.py

@@ -0,0 +1,102 @@
+from collections.abc import Callable, Hashable
+from enum import StrEnum
+
+from ..domain import Observation
+from ..domain.regional_scopes import RegionalScopes
+from .location_catalogue import LocationCatalogue
+
+DEFAULT_DAYS = 7
+NEARBY_DISTANCE_KM = 50
+# Nearby species queries have always used the eBird client's default radius rather than NEARBY_DISTANCE_KM.
+NEARBY_SPECIES_DISTANCE_KM = 25
+
+
+class ObservationKind(StrEnum):
+    RECENT = "recent"
+    NOTABLE = "notable"
+
+
+def latest_per(key: Callable[[Observation], Hashable], observations: list[Observation]) -> list[Observation]:
+    """The latest observation for each key, oldest first."""
+    latest = {}
+    for obs in observations:
+        if key(obs) not in latest or latest[key(obs)].observation_datetime < obs.observation_datetime:
+            latest[key(obs)] = obs
+    return sorted(latest.values(), key=lambda x: x.observation_datetime)
+
+
+def first_per(key: Callable[[Observation], Hashable], observations: list[Observation]) -> list[Observation]:
+    """The first observation eBird returned for each key, oldest first."""
+    first = {}
+    for obs in observations:
+        first.setdefault(key(obs), obs)
+    return sorted(first.values(), key=lambda x: x.observation_datetime)
+
+
+class ObservationQuery:
+    """Observations of a kind at a Location or nearby, from whichever eBird request that takes."""
+
+    def __init__(self, client, location_catalogue: LocationCatalogue, lat: str | None, long: str | None):
+        self.client = client
+        self.location_catalogue = location_catalogue
+        self.lat = lat
+        self.long = long
+
+    def observations(
+        self,
+        kind: ObservationKind,
+        scope: RegionalScopes,
+        region: str | None = None,
+        species_code: str | None = None,
+        back=DEFAULT_DAYS,
+    ) -> list[Observation]:
+        """Region None means the Home Region at that scope; nearby ignores it and needs the user's coordinates."""
+        if kind == ObservationKind.NOTABLE:
+            if species_code is not None:
+                raise ValueError("notable observations can't be narrowed to a species")
+            return first_per(lambda obs: (obs.location, obs.name), self.notable(scope, region, back))
+        if species_code is not None:
+            return latest_per(lambda obs: obs.location, self.species(scope, region, species_code, back))
+        return latest_per(lambda obs: obs.name, self.recent(scope, region, back))
+
+    def recent(self, scope: RegionalScopes, region: str | None, back) -> list[Observation]:
+        """Every species reported, as eBird returned them."""
+        if scope == RegionalScopes.NEARBY:
+            results = self.client.get_nearby_observations(
+                *self.coordinates(), dist=NEARBY_DISTANCE_KM, back=back, hotspot=True
+            )
+        else:
+            results = self.client.get_observations(self.location_ids(scope, region), back=back, hotspot=True)
+        return [Observation(result) for result in results]
+
+    def notable(self, scope: RegionalScopes, region: str | None, back) -> list[Observation]:
+        """Notable species reported, as eBird returned them."""
+        if scope == RegionalScopes.NEARBY:
+            results = self.client.get_nearby_notable(
+                *self.coordinates(), dist=NEARBY_DISTANCE_KM, back=back, hotspot=True
+            )
+        else:
+            results = self.client.get_notable_observations(self.location_ids(scope, region), back=back, hotspot=True)
+        return [Observation(result) for result in results]
+
+    def species(self, scope: RegionalScopes, region: str | None, species_code: str, back) -> list[Observation]:
+        """Reports of one species, as eBird returned them."""
+        if scope == RegionalScopes.NEARBY:
+            results = self.client.get_nearby_species(
+                species_code, *self.coordinates(), dist=NEARBY_SPECIES_DISTANCE_KM, back=back, hotspot=True
+            )
+        else:
+            results = self.client.get_species_observations(
+                species_code, self.location_ids(scope, region), back=back, hotspot=True
+            )
+        return [Observation(result) for result in results]
+
+    def coordinates(self) -> tuple[str, str]:
+        """The user's coordinates, which every nearby query needs."""
+        if self.lat is None or self.long is None:
+            raise ValueError("nearby needs coordinates: set --lat and --long, or EBIRDLAT and EBIRDLONG")
+        return self.lat, self.long
+
+    def location_ids(self, scope: RegionalScopes, region: str | None) -> list[str]:
+        """Location ids the region resolves to, each once."""
+        return list(dict.fromkeys(self.location_catalogue.resolve(scope, region)))