ebird-cli 0.1.0__py3-none-any.whl

ebird_cli/cli/__init__.py

@@ -0,0 +1,3 @@
+from .autocomplete import ContextSensitiveCompleter
+
+__all__ = ["ContextSensitiveCompleter"]

ebird_cli/cli/autocomplete.py

@@ -0,0 +1,30 @@
+from prompt_toolkit.completion import Completer, Completion, WordCompleter
+from prompt_toolkit.document import Document
+
+exit_program = "exit"
+
+
+class ContextSensitiveCompleter(Completer):
+    def __init__(self, commands):
+        self.first_word_completer = WordCompleter(
+            [cmd.command_name for cmd in commands] + [exit_program], ignore_case=True
+        )
+        self.command_completers = {cmd.command_name: cmd for cmd in commands}
+
+    def get_completions(self, document: Document, complete_event):
+        text = document.text_before_cursor
+        words = text.split(" ")
+        if not words or (len(words) == 1 and not text.endswith(" ")):
+            for completion in self.first_word_completer.get_completions(document, complete_event):
+                yield Completion(
+                    completion.text if completion.text == exit_program else completion.text + "",
+                    start_position=completion.start_position,
+                )
+        else:
+            command_name = words[0]
+            command = self.command_completers.get(command_name)
+            if not command:
+                yield Completion("", start_position=-len(document.get_word_before_cursor()))
+            else:
+                for completion in command.get_completions(document, complete_event):
+                    yield completion

ebird_cli/cli/command.py

@@ -0,0 +1,150 @@
+from dataclasses import dataclass
+
+from colorama import Fore
+from prompt_toolkit.document import Document
+
+from ..domain.regional_scopes import RegionalScopes
+from ..services.location_catalogue import LocationCatalogue
+from ..services.observation_query import ObservationKind, ObservationQuery
+from ..services.printing import PrintingService
+from ..services.taxonomy import TaxonomyService
+from ..utils.logger import logger
+from .grammar import Arguments, Flag, Grammar, Positional
+
+SCOPE = Positional("scope", choices=[scope.value for scope in RegionalScopes])
+BACK = Flag("back", default="7", choices=range(1, 31))
+
+
+def region_flag(location_catalogue: LocationCatalogue) -> Flag:
+    return Flag(
+        "region",
+        multi_word=True,
+        suggestions=lambda typed, arguments: location_catalogue.names(RegionalScopes(arguments["scope"]), typed),
+        hidden_when=lambda arguments: arguments.get("scope") == RegionalScopes.NEARBY,
+    )
+
+
+def species_flag(taxonomy_service: TaxonomyService) -> Flag:
+    return Flag(
+        "species",
+        multi_word=True,
+        suggestions=lambda typed, _arguments: taxonomy_service.search_by_common_name(typed) if typed else [],
+    )
+
+
+class Command:
+    def __init__(self, command_name: str, description: str, grammar: Grammar):
+        self.command_name = command_name
+        self.description = description
+        self.grammar = grammar
+
+    def run(self, arguments: Arguments):
+        raise NotImplementedError
+
+    def handle_command(self, *args):
+        logger.debug(f"user input: {args}")
+        self.run(self.grammar.parse(list(args)))
+
+    def get_completions(self, document: Document, _complete_event):
+        _command_name, _, text = document.text_before_cursor.partition(" ")
+        logger.debug(f"command get_completions: {text}")
+        yield from self.grammar.complete(text)
+
+    def command_example(self):
+        command_name = f"{Fore.RED}{self.command_name}{Fore.RESET}"
+        mandatory = [positional.name for positional in self.grammar.positionals]
+        optional = [flag.token for flag in self.grammar.flags]
+        mandatory_params = f"{Fore.MAGENTA}<{', '.join(mandatory)}>{Fore.RESET}" if mandatory else ""
+        optional_params = f"{Fore.CYAN}[{', '.join(optional)}]{Fore.RESET}" if optional else ""
+
+        return f"{command_name:18} {mandatory_params} {optional_params}"
+
+
+@dataclass
+class ObservationCommandArgs:
+    region: str | None
+    scope: RegionalScopes
+    back: str
+    species: str | None = None
+
+
+class ObservationCommand(Command):
+    kind: ObservationKind
+
+    def __init__(
+        self,
+        command_name: str,
+        description: str,
+        grammar: Grammar,
+        observation_query: ObservationQuery,
+        printing_service: PrintingService,
+    ):
+        super().__init__(command_name, description, grammar)
+        self.observation_query = observation_query
+        self.printing_service = printing_service
+
+    def run(self, arguments: Arguments):
+        logger.debug(f"run - arguments: {arguments}")
+        args = ObservationCommandArgs(
+            region=arguments["region"],
+            scope=RegionalScopes(arguments["scope"]),
+            back=arguments["back"],
+            species=arguments.get("species"),
+        )
+        self.handle_observation(args)
+
+    def handle_observation(self, args: ObservationCommandArgs):
+        self.print_observations(args)
+
+    def print_observations(self, args: ObservationCommandArgs, species_code: str | None = None):
+        observations = self.observation_query.observations(
+            self.kind, args.scope, args.region, species_code=species_code, back=args.back
+        )
+        self.printing_service.print_observations(observations)
+
+
+class RecentCommand(ObservationCommand):
+    kind = ObservationKind.RECENT
+
+    def __init__(
+        self,
+        observation_query: ObservationQuery,
+        location_catalogue: LocationCatalogue,
+        printing_service: PrintingService,
+        taxonomy_service: TaxonomyService,
+    ):
+        super().__init__(
+            "recent",
+            "Retrieve recent observations for the specified region",
+            Grammar([SCOPE], [region_flag(location_catalogue), species_flag(taxonomy_service), BACK]),
+            observation_query,
+            printing_service,
+        )
+        self.taxonomy_service = taxonomy_service
+
+    def handle_observation(self, args: ObservationCommandArgs):
+        species_code = None
+        if args.species:
+            species_codes = self.taxonomy_service.get_species_code(args.species)
+            if not species_codes:
+                return
+            species_code = species_codes[0]
+        self.print_observations(args, species_code)
+
+
+class NotableCommand(ObservationCommand):
+    kind = ObservationKind.NOTABLE
+
+    def __init__(
+        self,
+        observation_query: ObservationQuery,
+        location_catalogue: LocationCatalogue,
+        printing_service: PrintingService,
+    ):
+        super().__init__(
+            "notable",
+            "Retrieve notable observations for the specified region",
+            Grammar([SCOPE], [region_flag(location_catalogue), BACK]),
+            observation_query,
+            printing_service,
+        )

ebird_cli/cli/grammar.py

@@ -0,0 +1,197 @@
+"""The command-line grammar of a command: the words it accepts after its name, and what to offer while they're typed."""
+
+import re
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+
+from prompt_toolkit.completion import Completion
+
+FLAG_PREFIX = "-"
+
+Arguments = dict[str, str | None]
+
+
+class CommandLineError(Exception):
+    """A line that the command's grammar does not accept."""
+
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.message = message
+
+
+Choices = Sequence[str] | range
+
+
+def describe(choices: Choices) -> str:
+    if isinstance(choices, range):
+        return f"{choices.start} to {choices.stop - 1}"
+    return ", ".join(repr(choice) for choice in choices)
+
+
+def is_choice(word: str, choices: Choices) -> bool:
+    if isinstance(choices, range):
+        return word.isascii() and word.isdigit() and int(word) in choices
+    return word in choices
+
+
+@dataclass(frozen=True)
+class Positional:
+    """A mandatory word, before any flag, that must be one of choices."""
+
+    name: str
+    choices: Sequence[str]
+
+
+@dataclass(frozen=True)
+class Flag:
+    """An optional -name followed by its value: one word, or every word up to the next flag when multi_word.
+
+    A value given must be one of choices, when the flag has them; an absent flag has default. suggestions(typed,
+    arguments) gives the completions for what was typed after the flag; without it, completion offers the choices
+    containing it. The flag isn't offered while hidden_when(positional arguments) holds.
+    """
+
+    name: str
+    multi_word: bool = False
+    default: str | None = None
+    choices: Choices | None = None
+    suggestions: Callable[[str, Arguments], list[str]] | None = None
+    hidden_when: Callable[[Arguments], bool] = lambda _arguments: False
+
+    def complete(self, typed: str, arguments: Arguments) -> list[str]:
+        if self.suggestions is not None:
+            return self.suggestions(typed, arguments)
+        return [str(choice) for choice in self.choices or [] if typed in str(choice)]
+
+    @property
+    def token(self) -> str:
+        return f"{FLAG_PREFIX}{self.name}"
+
+
+class Grammar:
+    """The words a command accepts after its name."""
+
+    def __init__(self, positionals: Sequence[Positional], flags: Sequence[Flag]):
+        self.positionals = tuple(positionals)
+        self.flags = tuple(flags)
+
+    def parse(self, words: list[str]) -> Arguments:
+        """The value of each argument named in the line, or CommandLineError when the grammar does not accept it."""
+        return self._arguments(self._read(words))
+
+    def _arguments(self, reading: "_Reading", completing: Flag | None = None) -> Arguments:
+        """The arguments of a reading, not yet holding the value of the flag being completed to its choices."""
+        for flag in self.flags:
+            if reading.flag_words.get(flag.name) == []:
+                raise CommandLineError(f"argument {flag.token}: expected one argument")
+        for positional, word in self._typed_positionals(reading):
+            if not is_choice(word, positional.choices):
+                raise invalid_choice(positional.name, word, positional.choices)
+        missing = [positional.name for positional in self.positionals[len(reading.positional_words) :]]
+        if missing:
+            raise CommandLineError(f"the following arguments are required: {', '.join(missing)}")
+        unrecognized = reading.positional_words[len(self.positionals) :] + reading.unrecognized
+        if unrecognized:
+            raise CommandLineError(f"unrecognized arguments: {' '.join(unrecognized)}")
+
+        arguments = self._positional_arguments(reading)
+        for flag in self.flags:
+            values = reading.flag_words.get(flag.name)
+            value = " ".join(values) if values else flag.default
+            if values and flag.choices is not None and flag is not completing and not is_choice(value, flag.choices):
+                raise invalid_choice(flag.token, value, flag.choices)
+            arguments[flag.name] = value
+        return arguments
+
+    def complete(self, text: str) -> list[Completion]:
+        """What to offer for the word being typed at the end of text, the words after the command name."""
+        spans = [(match.start(), match.group()) for match in re.finditer(r"\S+", text)]
+        typed_start, typed = spans.pop() if text and not text[-1].isspace() else (len(text), "")
+        words = [word for _, word in spans]
+        starts = [start for start, _ in spans] + [typed_start]
+        reading = self._read(words)
+        if reading.flag is None and len(reading.positional_words) < len(self.positionals):
+            choices = self.positionals[len(reading.positional_words)].choices
+            return [
+                Completion(choice, start_position=-len(typed))
+                for choice in choices
+                if choice.lower().startswith(typed.lower())
+            ]
+        if typed.startswith(FLAG_PREFIX) or (typed == "" and not reading.takes_another_word()):
+            positional_arguments = self._positional_arguments(reading)
+            return [
+                Completion(flag.token, start_position=-len(typed))
+                for flag in self.flags
+                if flag.name not in reading.flag_words
+                and not flag.hidden_when(positional_arguments)
+                and typed.lower() in flag.token.lower()
+            ]
+        if not reading.takes_another_word():
+            return []
+        try:
+            arguments = self._arguments(self._read([*words, typed]), completing=reading.flag)
+        except CommandLineError:
+            return []
+        flag = reading.flag
+        typed_value = " ".join([*reading.flag_words[flag.name], typed])
+        start_position = starts[reading.flag_index + 1] - len(text)
+        return [Completion(value, start_position=start_position) for value in flag.complete(typed_value, arguments)]
+
+    def _typed_positionals(self, reading: "_Reading") -> list[tuple[Positional, str]]:
+        """Each positional with the word typed for it, for as many as the line has."""
+        return list(zip(self.positionals, reading.positional_words, strict=False))
+
+    def _positional_arguments(self, reading: "_Reading") -> Arguments:
+        return {positional.name: word for positional, word in self._typed_positionals(reading)}
+
+    def _flag(self, word: str) -> Flag | None:
+        """The flag a word names: exactly, or as a prefix of only that flag."""
+        matches = [flag for flag in self.flags if flag.token == word] or [
+            flag for flag in self.flags if flag.token.startswith(word)
+        ]
+        return matches[0] if len(matches) == 1 else None
+
+    def _read(self, words: list[str]) -> "_Reading":
+        reading = _Reading()
+        for index, word in enumerate(words):
+            if is_flag_token(word):
+                reading.flag = self._flag(word)
+                reading.flag_index = index
+                if reading.flag is None:
+                    reading.unrecognized.append(word)
+                else:
+                    reading.flag_words[reading.flag.name] = []
+            elif reading.takes_another_word():
+                reading.flag_words[reading.flag.name].append(word)
+            elif reading.flag is None and not reading.unrecognized and not reading.flag_words:
+                reading.positional_words.append(word)
+            else:
+                reading.unrecognized.append(word)
+        return reading
+
+
+def invalid_choice(name: str, word: str, choices: Choices) -> CommandLineError:
+    return CommandLineError(f"argument {name}: invalid choice: {word!r} (choose from {describe(choices)})")
+
+
+def is_flag_token(word: str) -> bool:
+    """Whether a word names a flag; a dash before a digit, as in -3, is a value."""
+    return word.startswith(FLAG_PREFIX) and word[len(FLAG_PREFIX) : len(FLAG_PREFIX) + 1].isalpha()
+
+
+@dataclass
+class _Reading:
+    """The words of a line sorted into positionals, the values of each flag, and words no argument takes.
+
+    flag is the flag whose value is being read at the end of the line, and flag_index its position among the words.
+    """
+
+    positional_words: list[str] = field(default_factory=list)
+    flag_words: dict[str, list[str]] = field(default_factory=dict)
+    unrecognized: list[str] = field(default_factory=list)
+    flag: Flag | None = None
+    flag_index: int = -1
+
+    def takes_another_word(self) -> bool:
+        """Whether the flag being read would take the next word as part of its value."""
+        return self.flag is not None and (self.flag.multi_word or not self.flag_words[self.flag.name])

ebird_cli/domain/__init__.py

@@ -0,0 +1,4 @@
+from .observation import Observation
+from .taxonomy import TaxonomyEntry
+
+__all__ = ["Observation", "TaxonomyEntry"]

ebird_cli/domain/fields.py

@@ -0,0 +1,20 @@
+from enum import StrEnum
+
+
+class EbirdFields(StrEnum):
+    observation_date = "obsDt"
+    location_name = "locName"
+    location_id = "locId"
+    common_name = "comName"
+    country_code = "countryCode"
+    subnational_name = "subnational1Name"
+    subnational_code = "subnational1Code"
+    sub_subnational_name = "subnational2Name"
+    sub_subnational_code = "subnational2Code"
+    name = "name"
+    code = "code"
+    species_code = "speciesCode"
+
+
+class ExportFields(StrEnum):
+    common_name = "Common Name"

ebird_cli/domain/observation.py

@@ -0,0 +1,21 @@
+import re
+from datetime import datetime
+
+from .fields import EbirdFields
+
+regex_filter = r"\([^)]*\)"
+
+datetime_format = "%Y-%m-%d %H:%M"
+date_format = "%Y-%m-%d"
+
+
+class Observation:
+    def __init__(self, observation):
+        self.observation_date = observation[EbirdFields.observation_date][0:10]
+        if len(observation[EbirdFields.observation_date]) > 10:
+            self.observation_datetime = datetime.strptime(observation[EbirdFields.observation_date], datetime_format)
+        else:
+            self.observation_datetime = datetime.strptime(observation[EbirdFields.observation_date], date_format)
+        self.location = re.sub(regex_filter, "", observation[EbirdFields.location_name]).split(",")[0][0:55]
+        self.name = re.sub(regex_filter, "", observation[EbirdFields.common_name]).strip()
+        self.subname = observation.get(EbirdFields.sub_subnational_name, "")

ebird_cli/domain/region.py

@@ -0,0 +1,6 @@
+class Region:
+    def __init__(self, ebird_region: str):
+        region_segments = ebird_region.split("-")
+        self.national = region_segments[0]
+        self.subnational = f"{region_segments[0]}-{region_segments[1]}"
+        self.regional = ebird_region

ebird_cli/domain/regional_scopes.py

@@ -0,0 +1,9 @@
+from enum import StrEnum
+
+
+class RegionalScopes(StrEnum):
+    HOTSPOT = "hotspot"
+    NEARBY = "nearby"
+    REGIONAL = "regional"
+    SUBNATIONAL = "subnational"
+    # NATIONAL = "national"

ebird_cli/domain/taxonomy.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class TaxonomyEntry:
+    sci_name: str
+    com_name: str
+    species_code: str
+    category: str
+    taxon_order: float
+    order: str
+    family_code: str
+    family_com_name: str
+    family_sci_name: str
+    banding_codes: list[str] = field(default_factory=list)
+    com_name_codes: list[str] = field(default_factory=list)
+    sci_name_codes: list[str] = field(default_factory=list)
+    report_as: str | None = None
+
+    @classmethod
+    def from_json(cls, data: dict) -> "TaxonomyEntry":
+        return cls(
+            sci_name=data["sciName"],
+            com_name=data["comName"],
+            species_code=data["speciesCode"],
+            category=data["category"],
+            taxon_order=data["taxonOrder"],
+            order=data.get("order", ""),
+            family_code=data.get("familyCode", ""),
+            family_com_name=data.get("familyComName", ""),
+            family_sci_name=data.get("familySciName", ""),
+            banding_codes=data.get("bandingCodes", []),
+            com_name_codes=data.get("comNameCodes", []),
+            sci_name_codes=data.get("sciNameCodes", []),
+            report_as=data.get("reportAs"),
+        )

ebird_cli/domain/taxonomy_cache.py

@@ -0,0 +1,9 @@
+import pandas
+
+from ..domain.region import Region
+
+
+class TaxonomyCache:
+    def __init__(self, region: Region, national_taxonomy: str):
+        self.national: pandas.DataFrame = pandas.read_csv(national_taxonomy)
+        self.region = region

ebird_cli/download_lists.py

@@ -0,0 +1,52 @@
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from requests import Session
+
+
+def download_csv(http_session, session_id, download_url, output_file):
+    headers = {"User-Agent": "Mozilla/5.0"}
+
+    response = http_session.get(download_url, cookies={"EBIRD_SESSIONID": session_id}, headers=headers)
+
+    if response.status_code == 200:
+        output_path = Path(output_file)
+
+        if not output_path.parent.exists():
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        output_path.write_bytes(response.content)
+    else:
+        print(f"Failed to download file. HTTP Status Code: {response.status_code}")
+        print("Response:", response.text)
+
+
+def main(argv=None, http_session=None):
+    argv = sys.argv[1:] if argv is None else argv
+
+    if len(argv) != 2:
+        print("Usage: ebird-cli-download-lists <session_id> <output_dir>")
+        sys.exit(1)
+
+    session_id, output_dir = argv
+    http_session = Session() if http_session is None else http_session
+
+    download_csv(
+        http_session,
+        session_id,
+        "https://ebird.org/lifelist?r=world&time=life&fmt=csv",
+        os.path.join(output_dir, "life_list.csv"),
+    )
+    current_year = datetime.now().year
+    download_csv(
+        http_session,
+        session_id,
+        f"https://ebird.org/lifelist?r=world&time=year&year={current_year}&fmt=csv",
+        os.path.join(output_dir, "year_list.csv"),
+    )
+
+
+if __name__ == "__main__":
+    main()