ebird-api-data 0.1.0__py3-none-any.whl

ebird/api/data/models/observer.py

@@ -0,0 +1,48 @@
+from django.db import models
+from django.utils.translation import gettext_lazy as _
+
+
+class Observer(models.Model):
+    class Meta:
+        verbose_name = _("observer")
+        verbose_name_plural = _("observers")
+
+    identifier = models.TextField(
+        verbose_name=_("identifier"),
+        help_text=_("The code for the person submitted the checklist."),
+    )
+
+    name = models.TextField(
+        verbose_name=_("name"),
+        help_text=_("The display name of the observer."),
+    )
+
+    original = models.TextField(
+        verbose_name=_("original name"),
+        help_text=_("The original name of the observer from eBird."),
+    )
+
+    multiple = models.BooleanField(
+        default=False,
+        verbose_name=_("Multiple accounts"),
+        help_text=_("Is the name used by more than one eBird account."),
+    )
+
+    enabled = models.BooleanField(
+        default=True,
+        verbose_name=_("Enabled"),
+        help_text=_("Load checklists from the eBird observer."),
+    )
+
+    data = models.JSONField(
+        verbose_name=_("Data"),
+        help_text=_("Data describing an Observer."),
+        default=dict,
+        blank=True,
+    )
+
+    def __repr__(self) -> str:
+        return str(self.identifier)
+
+    def __str__(self) -> str:
+        return str(self.name)

ebird/api/data/models/species.py

@@ -0,0 +1,118 @@
+import json
+import logging
+
+from json import JSONDecodeError
+
+from django.db import models
+from django.utils.translation import get_language
+from django.utils.translation import gettext_lazy as _
+
+log = logging.getLogger(__name__)
+
+
+class Species(models.Model):
+    class Category(models.TextChoices):
+        ALL = "", _("All categories")
+        SPECIES = "species", _("Species")
+        SUBSPECIES = "issf", _("Subspecies")
+        DOMESTIC = "domestic", _("Domestic")
+        HYBRID = "hybrid", _("Hybrid")
+
+    class Meta:
+        verbose_name = _("species")
+        verbose_name_plural = _("species")
+
+    taxon_order = models.IntegerField(
+        blank=True,
+        null=True,
+        verbose_name=_("taxonomy order"),
+        help_text=_("The position in the eBird/Clements taxonomic order."),
+    )
+
+    order = models.TextField(
+        blank=True,
+        verbose_name=_("order"),
+        help_text=_(
+            "The order, e.g. Struthioniformes, from the eBird/Clements taxonomy."
+        ),
+    )
+
+    category = models.TextField(
+        blank=True,
+        choices=Category,
+        verbose_name=_("category"),
+        help_text=_("The category from the eBird/Clements taxonomy."),
+    )
+
+    species_code = models.TextField(
+        blank=True,
+        verbose_name=_("species code"),
+        help_text=_("The species code, e.g. ostric2, used in the eBird API."),
+    )
+
+    family_code = models.TextField(
+        blank=True,
+        verbose_name=_("family code"),
+        help_text=_("The family code, e.g. struth1, used in the eBird API."),
+    )
+
+    common_name = models.TextField(
+        verbose_name=_("common name"),
+        help_text=_("The species common name in the eBird/Clements taxonomy."),
+    )
+
+    scientific_name = models.TextField(
+        verbose_name=_("scientific name"),
+        help_text=_("The species scientific name in the eBird/Clements taxonomy."),
+    )
+
+    family_common_name = models.TextField(
+        blank=True,
+        verbose_name=_("family common name"),
+        help_text=_(
+            "The common name for the species family in the eBird/Clements taxonomy."
+        ),
+    )
+
+    family_scientific_name = models.TextField(
+        blank=True,
+        verbose_name=_("family scientific name"),
+        help_text=_(
+            "The scientific name for the species family in the eBird/Clements taxonomy."
+        ),
+    )
+
+    data = models.JSONField(
+        verbose_name=_("Data"),
+        help_text=_("Data describing a Species."),
+        default=dict,
+        blank=True,
+    )
+
+    def __repr__(self) -> str:
+        return str(self.species_code)
+
+    def __str__(self) -> str:
+        return self.get_common_name()
+
+    def get_common_name(self) -> str:
+        try:
+            data = json.loads(self.common_name)
+            common_name = data.get(get_language(), "")
+            if not common_name:
+                common_name = data.get(next(iter(data)), "")
+        except JSONDecodeError:
+            log.error("Incorrect JSON for Species common_name: %s", self.id)
+            common_name = ""
+        return common_name
+
+    def get_family_common_name(self) -> str:
+        try:
+            data = json.loads(self.family_common_name)
+            family_name = data.get(get_language(), "")
+            if not family_name:
+                family_name = data.get(next(iter(data)), "")
+        except JSONDecodeError:
+            log.error("Incorrect JSON for Species family_name: %s", self.id)
+            family_name = ""
+        return family_name

ebird/api/data/models/state.py

@@ -0,0 +1,29 @@
+from django.db import models
+from django.utils.translation import gettext_lazy as _
+
+
+class State(models.Model):
+    class Meta:
+        verbose_name = _("state")
+        verbose_name_plural = _("states")
+
+    code = models.CharField(
+        max_length=10,
+        db_index=True,
+        verbose_name=_("code"),
+        help_text=_("The code used to identify the state."),
+    )
+
+    name = models.TextField(
+        verbose_name=_("name"), help_text=_("The name of the state.")
+    )
+
+    place = models.TextField(
+        verbose_name=_("place"), help_text=_("The hierarchical name of the state.")
+    )
+
+    def __repr__(self) -> str:
+        return str(self.code)
+
+    def __str__(self) -> str:
+        return str(self.name)

ebird/api/data/widgets.py

@@ -0,0 +1,46 @@
+import json
+
+from django import forms
+from django.conf import settings
+from django.utils.translation import gettext_lazy as _
+
+
+class TranslationTextInput(forms.MultiWidget):
+    template_name = "data/widgets/translation_field.html"
+
+    def __init__(self, *args, **kwargs):
+        widgets = [
+            forms.TextInput(attrs={"locale": _(language), "class": "vTextField"})
+            for code, language in settings.LANGUAGES
+        ]
+        super().__init__(widgets, **kwargs)
+
+    def decompress(self, value):
+        if value:
+            data = json.loads(value)
+            return [data.get(code, "") for code, language in settings.LANGUAGES]
+        return []
+
+
+class TranslationTextarea(forms.MultiWidget):
+    template_name = "data/widgets/translation_field.html"
+
+    def __init__(self, *args, **kwargs):
+        if "widgets" not in kwargs:
+            kwargs["widgets"] = [
+                forms.Textarea(
+                    attrs={
+                        "locale": _(language),
+                        "rows": 10,
+                        "class": "vLargeTextField",
+                    }
+                )
+                for code, language in settings.LANGUAGES
+            ]
+        super().__init__(**kwargs)
+
+    def decompress(self, value):
+        if value:
+            data = json.loads(value)
+            return [data.get(code, "") for code, language in settings.LANGUAGES]
+        return []

ebird_api_data-0.1.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: ebird-api-data
+Version: 0.1.0
+Summary: eBird API Data is a reusable Django app for loading data from eBird into a database.
+Author-email: Stuart MacKay <smackay@flagstonesoftware.com>
+License: The MIT License (MIT)
+        
+        Copyright (c) 2025 Stuart MacKay
+        
+        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.
+        
+Keywords: checklists,observations,species,Django,eBird,models
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+Requires-Dist: beautifulsoup4>=4.13.3
+Requires-Dist: django>=4.2
+Requires-Dist: ebird-api-requests>=4.0.1
+Requires-Dist: ebird-codes>=0.0.2
+Requires-Dist: lxml>=6.0.0
+
+eBird API Data
+==============
+eBird API Data is a reusable Django app for loading data from eBird into a database.
+
+Overview
+--------
+.. overview-start
+
+The Cornell Laboratory of Ornithology in Ithaca, New York runs the eBird database
+which collects observations of birds from all over the world. All the observations
+are published on `eBird.org`_, and they also make them available via an `API`_.
+This project contains a loader and models to take data from the API and load it into
+a database. From there you can analyse the data with python, jupyter notebooks, or
+build a web site.
+
+To get started, you will need to `sign up`_ for an eBird account, if you don't
+already have one and `register`_ to get an API key. Make sure you read and
+understand the `Terms of use`_, and remember bandwidth and servers cost money,
+so don't abuse the service. If you need large numbers of observations, then
+sign up to receive the `eBird Basic Dataset`_.
+
+.. _eBird.org: https://ebird.org
+.. _API: https://documenter.getpostman.com/view/664302/S1ENwy59
+.. _sign up: https://secure.birds.cornell.edu/identity/account/create
+.. _register: https://ebird.org/data/download
+.. _Terms of use: https://www.birds.cornell.edu/home/ebird-api-terms-of-use/
+.. _eBird Basic Dataset: https://science.ebird.org/en/use-ebird-data/download-ebird-data-products
+
+.. overview-end
+
+Install
+-------
+.. install-start
+
+You can use either `pip`_ or `uv`_ to download the `package`_ from PyPI and
+install it into a virtualenv:
+
+.. code-block:: console
+
+    pip install ebird-api-data
+
+or:
+
+.. code-block:: console
+
+    uv add ebird-api-data
+
+Update ``INSTALLED_APPS`` in your Django setting:
+
+.. code-block:: python
+
+    INSTALLED_APPS = [
+        ...
+        ebird.api.data
+    ]
+
+Finally, run the migrations to create the tables:
+
+.. code-block:: python
+
+    python manage.py migrate
+
+.. _pip: https://pip.pypa.io/en/stable/
+.. _uv: https://docs.astral.sh/uv/
+.. _package: https://pypi.org/project/ebird-api-data/
+
+.. install-end
+
+Demo
+----
+
+.. demo-start
+
+If you check out the code from the repository there is a fully functioning
+Django site. It only contains the admin pages, but that is sufficient for
+you to browse the data.
+
+.. code-block:: console
+
+    git clone git@github.com:StuartMacKay/ebird-api-data.git
+    cd ebird-api-data
+
+Create the virtual environment:
+
+.. code-block:: console
+
+    uv venv
+
+Activate it:
+
+.. code-block:: console
+
+    source venv/bin/activate
+
+Install the requirements:
+
+.. code-block:: console
+
+    uv sync
+
+Run the database migrations:
+
+.. code-block:: console
+
+    python manage.py migrate
+
+Create a user:
+
+.. code-block:: console
+
+    python manage.py createsuperuser
+
+Create a copy of the .env.example file and add your API key:
+
+.. code-block:: console
+
+    cp .env.example .env
+
+.. code-block:: console
+
+    EBIRD_API_KEY=<my api key>
+
+Now, download data from the API:
+
+.. code-block:: console
+
+    python manage.py add_checklists --days 2 US-NY-109
+
+This loads all the checklists, submitted in the past two days by birders in
+Tompkins County, New York, where the Cornell Lab is based. You can use any
+location code used by eBird, whether it's for a country, state/region, or
+county. Remember, read the terms of use.
+
+Run the demo:
+
+.. code-block:: console
+
+    python manage.py runserver
+
+Now log into the `Django Admin <http:localhost:8000/admin>` to browse the tables.
+
+.. demo-end
+
+Project Information
+-------------------
+
+* Documentation: https://ebird-api-data.readthedocs.io/en/latest/
+* Issues: https://github.com/StuartMacKay/ebird-api-data/issues
+* Repository: https://github.com/StuartMacKay/ebird-api-data
+
+The app is tested on Python 3.10+, and officially supports Django 4.2, 5.0 and 5.1.
+
+eBird API Data is released under the terms of the `MIT`_ license.
+
+.. _MIT: https://opensource.org/licenses/MIT

ebird_api_data-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+ebird/api/data/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+ebird/api/data/admin.py,sha256=SQWBoTzd2yrk9EdftwguJJ5ZdUkIjMVuW_ykEgyPIr8,12642
+ebird/api/data/apps.py,sha256=o8wTQ_g9bgGXyEBXdmoj2y1SLUng8r0Mzsyg5uSXFCc,192
+ebird/api/data/fields.py,sha256=TkWQL_bmct4t-RmIWKrBHk_OZQzikGS9H4LHV9dKVOY,1693
+ebird/api/data/loaders.py,sha256=TgnvDmxqABouELyIbLcZ9vDio8FNkvTLrfezT6pzjT4,18041
+ebird/api/data/widgets.py,sha256=R7UZAcd2Eh4pgRN8epfAbKJEjiriW7FYHWa2RV8F98w,1419
+ebird/api/data/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ebird/api/data/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ebird/api/data/management/commands/add_checklists.py,sha256=_jw1jjfsPY9UyEUse-BdTBdrUGzYUlPx0uXz1LMjYhs,4853
+ebird/api/data/migrations/0001_initial.py,sha256=lvTE6LDlDFEHdKatX26_lFSwNy8Ut7b0sWdnj4ovS2Q,33841
+ebird/api/data/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ebird/api/data/models/__init__.py,sha256=sk5oRhvJwa1AHlYKprgcC8DMnMxZZ77FXGkbR2DXKz8,423
+ebird/api/data/models/checklist.py,sha256=sLc0a1UBDVgeAeei7zyNAEVybWEJxUNnVsMwkKnYdjo,4747
+ebird/api/data/models/country.py,sha256=Z-k7mIxzZWuBNP2dtge8Q64WjM5tOyMROp9UDZLk9UA,742
+ebird/api/data/models/county.py,sha256=kshpq35w_JWAYit9wqgP44QQ2NjJwy_njH-GrUn-1-Q,737
+ebird/api/data/models/filter.py,sha256=hwwz2Vlmpj-4XRm_yz1j_M4UPdDms8AX4x-95WsdK14,1859
+ebird/api/data/models/location.py,sha256=HSz848qQUNU3G2NGHRH5Gg7dEB4qbZOvXFYOJbh1jYk,5537
+ebird/api/data/models/observation.py,sha256=18YSIpq3aq_9DjH7LF2HpGveLb9h3wRxGNoQpE5cBQI,5201
+ebird/api/data/models/observer.py,sha256=M3OllGp391wDsgwJD8j639qeLRQ_MV5kiCW5HoQ6NB4,1284
+ebird/api/data/models/species.py,sha256=ZmUrn7iLYw4FFIOVWSo0dX9U7KnRC8r2NlmAsH-ierw,3524
+ebird/api/data/models/state.py,sha256=9xZOwjwuM4YLx5wva3wGXYH50oz_oHXOhbGqmyCAoaQ,730
+ebird_api_data-0.1.0.dist-info/METADATA,sha256=hvaNtTpszEcWaLcdaDTmgRQk1cUabl6BEh8IIMH4rZA,6284
+ebird_api_data-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ebird_api_data-0.1.0.dist-info/top_level.txt,sha256=lBp3I23K75tsPJn7Jdz7d4Tk7JeRhbVkcuGthNk7LaM,6
+ebird_api_data-0.1.0.dist-info/RECORD,,

ebird_api_data-0.1.0.dist-info/WHEEL

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

ebird_api_data-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ebird