ebird-api-data 0.1.1__tar.gz → 0.2.1__tar.gz

ebird_api_data-0.2.1/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: ebird-api-data
+Version: 0.2.1
+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-Expression: MIT
+License-File: LICENSE
+Keywords: Django,checklists,eBird,models,observations,species
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Science/Research
+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
+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
+Description-Content-Type: text/markdown
+
+# eBird API Data
+
+eBird API Data is a reusable Django app for loading data from eBird into a database.
+
+## Overview
+
+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](https://ebird.org), and they also make them available
+via an [API](https://documenter.getpostman.com/view/664302/S1ENwy59). 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](https://secure.birds.cornell.edu/identity/account/create)
+for an eBird account, if you don't already have one and
+[register](https://ebird.org/data/download)
+to get an API key. Make sure you read and understand the
+[Terms of use](https://www.birds.cornell.edu/home/ebird-api-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](https://science.ebird.org/en/use-ebird-data/download-ebird-data-products).
+
+## Install
+
+You can use either [pip](https://pip.pypa.io/en/stable/) or [uv](https://docs.astral.sh/uv/)
+to download the [package](https://pypi.org/project/ebird-api-data/) from PyPI and
+install it into a virtualenv:
+
+```shell
+pip install ebird-api-data
+```
+
+or:
+
+```shell
+uv add ebird-api-data
+```
+
+Update `INSTALLED_APPS` in your Django setting:
+
+```python
+INSTALLED_APPS = [
+    ...
+    ebird.api.data
+]
+```
+
+Finally, run the migrations to create the tables:
+
+```python
+python manage.py migrate
+```
+
+## Demo
+
+If you check out the code from the repository there is a fully functioning
+Django site. It contains pages for checklists, observations and species,
+where you can browse the records or search by location, observer. date. etc. 
+The Django Admin lets you browse and edit the records in the database.
+
+```shell
+git clone git@github.com:StuartMacKay/ebird-api-data.git
+cd ebird-api-data
+```
+
+Create the virtual environment:
+```shell
+uv venv
+```
+
+Activate it:
+```shell
+source .venv/bin/activate
+```
+
+Install the requirements:
+```shell
+uv sync
+```
+
+Create a copy of the .env.example file and add your API key:
+```shell
+cp .env.example .env
+```
+
+For example:
+```shell
+EBIRD_API_KEY=<my api key>
+```
+
+Run the database migrations:
+```shell
+python manage.py migrate
+```
+
+Create a user:
+```shell
+python manage.py createsuperuser
+```
+
+Create a copy of the .env.example file and add your API key:
+```shell
+cp .env.example .env
+```
+
+```shell
+EBIRD_API_KEY=<my api key>
+```
+
+Now, download data from the API:
+
+```shell
+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:
+
+```shell
+python manage.py runserver
+```
+
+Now, either visit the site, http:localhost:8000/, or log into the Django Admin, 
+http:localhost:8000/admin to browse the tables.
+
+## Project Information
+
+* Documentation: https://ebird-api-data.readthedocs.io/en/latest/
+* Issues: https://todo.sr.ht/~smackay/ebird-api-data
+* Repository: https://git.sr.ht/~smackay/ebird-api-data
+* Announcements: https://lists.sr.ht/~smackay/ebirders-announce
+* Discussions: https://lists.sr.ht/~smackay/ebirders-discuss
+* Development: https://lists.sr.ht/~smackay/ebirders-develop
+
+The repository is also mirrored on Github:
+
+* 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.
+
+## License
+
+eBird API Data is released under the terms of the [MIT](https://opensource.org/licenses/MIT) license.

ebird_api_data-0.2.1/README.md

@@ -0,0 +1,149 @@
+# eBird API Data
+
+eBird API Data is a reusable Django app for loading data from eBird into a database.
+
+## Overview
+
+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](https://ebird.org), and they also make them available
+via an [API](https://documenter.getpostman.com/view/664302/S1ENwy59). 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](https://secure.birds.cornell.edu/identity/account/create)
+for an eBird account, if you don't already have one and
+[register](https://ebird.org/data/download)
+to get an API key. Make sure you read and understand the
+[Terms of use](https://www.birds.cornell.edu/home/ebird-api-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](https://science.ebird.org/en/use-ebird-data/download-ebird-data-products).
+
+## Install
+
+You can use either [pip](https://pip.pypa.io/en/stable/) or [uv](https://docs.astral.sh/uv/)
+to download the [package](https://pypi.org/project/ebird-api-data/) from PyPI and
+install it into a virtualenv:
+
+```shell
+pip install ebird-api-data
+```
+
+or:
+
+```shell
+uv add ebird-api-data
+```
+
+Update `INSTALLED_APPS` in your Django setting:
+
+```python
+INSTALLED_APPS = [
+    ...
+    ebird.api.data
+]
+```
+
+Finally, run the migrations to create the tables:
+
+```python
+python manage.py migrate
+```
+
+## Demo
+
+If you check out the code from the repository there is a fully functioning
+Django site. It contains pages for checklists, observations and species,
+where you can browse the records or search by location, observer. date. etc. 
+The Django Admin lets you browse and edit the records in the database.
+
+```shell
+git clone git@github.com:StuartMacKay/ebird-api-data.git
+cd ebird-api-data
+```
+
+Create the virtual environment:
+```shell
+uv venv
+```
+
+Activate it:
+```shell
+source .venv/bin/activate
+```
+
+Install the requirements:
+```shell
+uv sync
+```
+
+Create a copy of the .env.example file and add your API key:
+```shell
+cp .env.example .env
+```
+
+For example:
+```shell
+EBIRD_API_KEY=<my api key>
+```
+
+Run the database migrations:
+```shell
+python manage.py migrate
+```
+
+Create a user:
+```shell
+python manage.py createsuperuser
+```
+
+Create a copy of the .env.example file and add your API key:
+```shell
+cp .env.example .env
+```
+
+```shell
+EBIRD_API_KEY=<my api key>
+```
+
+Now, download data from the API:
+
+```shell
+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:
+
+```shell
+python manage.py runserver
+```
+
+Now, either visit the site, http:localhost:8000/, or log into the Django Admin, 
+http:localhost:8000/admin to browse the tables.
+
+## Project Information
+
+* Documentation: https://ebird-api-data.readthedocs.io/en/latest/
+* Issues: https://todo.sr.ht/~smackay/ebird-api-data
+* Repository: https://git.sr.ht/~smackay/ebird-api-data
+* Announcements: https://lists.sr.ht/~smackay/ebirders-announce
+* Discussions: https://lists.sr.ht/~smackay/ebirders-discuss
+* Development: https://lists.sr.ht/~smackay/ebirders-develop
+
+The repository is also mirrored on Github:
+
+* 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.
+
+## License
+
+eBird API Data is released under the terms of the [MIT](https://opensource.org/licenses/MIT) license.

{ebird_api_data-0.1.1 → ebird_api_data-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ebird-api-data"
-version = "0.1.1"
+version = "0.2.1"
 description = "eBird API Data is a reusable Django app for loading data from eBird into a database."
 keywords = ["checklists", "observations", "species", "Django", "eBird", "models"]
 license = "MIT"
@@ -8,7 +8,7 @@ license-files = ["LICENSE"]
 authors = [
   {name = "Stuart MacKay", email = "smackay@flagstonesoftware.com"},
 ]
-readme = "README.rst"
+readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
     "beautifulsoup4>=4.13.3",
@@ -61,10 +61,11 @@ dev-dependencies = [
     "django-extensions>=3.2.3",
     "psycopg2-binary>=2.9.10",
     "ipython>=8.37.0",
+    "django-autocomplete-light>=3.12.1",
 ]
 
 [tool.bumpversion]
-current_version = "0.1.1"
+current_version = "0.2.1"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 ignore_missing_version = false
@@ -89,16 +90,15 @@ search = 'release = "{current_version}"'
 replace = 'release = "{new_version}"'
 
 [[tool.bumpversion.files]]
-filename = "CHANGELOG.rst"
+filename = "CHANGELOG.md"
 search = """
-Latest
-------"""
+## Latest
+"""
 replace = """
-Latest
-------
+## Latest
 
-{new_version} ({now:%Y-%m-%d})
-------------------"""
+## {new_version}
+"""
 
 [[tool.bumpversion.files]]
 filename = "pyproject.toml"

ebird_api_data-0.2.1/src/ebird/api/data/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.1"

{ebird_api_data-0.1.1 → ebird_api_data-0.2.1}/src/ebird/api/data/loaders.py

@@ -303,19 +303,31 @@ class APILoader:
 
     def get_observer(self, data: dict) -> Observer:
         name: str = data.get("userDisplayName", "Anonymous eBirder")
-        observer, created = Observer.objects.get_or_create(
-            original=name, defaults={"name": name}
-        )
-        if observer.multiple:
+        is_multiple = Observer.objects.filter(original=name, multiple=True).exists()
+        if is_multiple:
+            identifier = self.get_observer_identifier(data)
             observer, created = Observer.objects.get_or_create(
-                identifier=self.get_observer_identifier(data),
-                defaults={"original": random_word(8), "name": name},
+                identifier=identifier,
+                defaults={
+                    "name":name,
+                    "original": random_word(8)
+                }
             )
-        elif observer.identifier == "":
-            observer.identifier = self.get_observer_identifier(data)
-            observer.save()
+        else:
+            if observer := Observer.objects.filter(original=name).first():
+                created = False
+            else:
+                identifier = self.get_observer_identifier(data)
+                observer, created = Observer.objects.get_or_create(
+                    identifier=identifier,
+                    defaults={"name": name, "original":name,}
+                )
+
         if created:
-            logger.info("Added observer: %s", observer.name)
+            logger.info("Added observer: %s", name)
+            if Observer.objects.filter(original=name).count() > 1:
+                logger.error("Multiple observers exist with same name: %s", name)
+
         return observer
 
     def add_checklist(self, identifier: str) -> Checklist | None:

ebird_api_data-0.2.1/src/ebird/api/data/migrations/0002_convert_foreign_keys_to_integers.py

@@ -0,0 +1,103 @@
+# Generated by Django 5.2.4 on 2025-07-14 09:34
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('data', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='checklist',
+            name='country',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='checklist',
+            name='county',
+            field=models.IntegerField(null=True),
+        ),
+        migrations.AlterField(
+            model_name='checklist',
+            name='location',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='checklist',
+            name='observer',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='checklist',
+            name='state',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='filter',
+            name='location',
+            field=models.IntegerField(null=True),
+        ),
+        migrations.AlterField(
+            model_name='filter',
+            name='species',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='filter',
+            name='update_species',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='location',
+            name='country',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='location',
+            name='county',
+            field=models.IntegerField(null=True),
+        ),
+        migrations.AlterField(
+            model_name='location',
+            name='state',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='observation',
+            name='checklist',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='observation',
+            name='country',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='observation',
+            name='county',
+            field=models.IntegerField(null=True),
+        ),
+        migrations.AlterField(
+            model_name='observation',
+            name='location',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='observation',
+            name='observer',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='observation',
+            name='species',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='observation',
+            name='state',
+            field=models.IntegerField(),
+        ),
+    ]

ebird_api_data-0.2.1/src/ebird/api/data/migrations/0003_make_codes_and_identifiers_primary_keys.py

@@ -0,0 +1,93 @@
+# Generated by Django 5.2.4 on 2025-07-14 09:49
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('data', '0002_convert_foreign_keys_to_integers'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='checklist',
+            name='id',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='country',
+            name='id',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='county',
+            name='id',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='location',
+            name='id',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='observation',
+            name='id',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='observer',
+            name='id',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='species',
+            name='id',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='state',
+            name='id',
+            field=models.IntegerField(),
+        ),
+        migrations.AlterField(
+            model_name='checklist',
+            name='identifier',
+            field=models.CharField(help_text='The unique identifier for the checklist.', max_length=15, primary_key=True, serialize=False, verbose_name='identifier'),
+        ),
+        migrations.AlterField(
+            model_name='country',
+            name='code',
+            field=models.CharField(help_text='The code used to identify the country.', max_length=2, primary_key=True, serialize=False, verbose_name='code'),
+        ),
+        migrations.AlterField(
+            model_name='county',
+            name='code',
+            field=models.CharField(help_text='The code used to identify the county.', max_length=10, primary_key=True, serialize=False, verbose_name='code'),
+        ),
+        migrations.AlterField(
+            model_name='location',
+            name='identifier',
+            field=models.CharField(help_text='The unique identifier for the location.', max_length=15, primary_key=True, serialize=False, verbose_name='identifier'),
+        ),
+        migrations.AlterField(
+            model_name='observation',
+            name='identifier',
+            field=models.CharField(help_text='A global unique identifier for the observation.', max_length=15, primary_key=True, serialize=False, verbose_name='identifier'),
+        ),
+        migrations.AlterField(
+            model_name='observer',
+            name='identifier',
+            field=models.CharField(help_text='The code for the person submitted the checklist.', max_length=15, primary_key=True, serialize=False, verbose_name='identifier'),
+        ),
+        migrations.AlterField(
+            model_name='species',
+            name='species_code',
+            field=models.CharField(help_text='The species code, e.g. ostric2, used in the eBird API.', max_length=10, primary_key=True, serialize=False, verbose_name='species code'),
+        ),
+        migrations.AlterField(
+            model_name='state',
+            name='code',
+            field=models.CharField(help_text='The code used to identify the state.', max_length=6, primary_key=True, serialize=False, verbose_name='code'),
+        ),
+    ]