project: Initial commit for initial release

.editorconfig

@@ -0,0 +1,30 @@
+# http://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{py,rst,ini}]
+indent_style = space
+indent_size = 4
+
+[*.{css,html,json,scss,yml,xml}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab
+
+[*.mk]
+indent_style = tab
+
+[*.cfg]
+indent_style = tab
+trim_trailing_whitespace = false

.env.example

@@ -0,0 +1,5 @@
+# Environment variables for working with the eBird API.
+
+# Your key to access the eBird API, see https://ebird.org/api/keygen.
+# It's set here so you don't commit it accidentally to a repository.
+EBIRD_API_KEY=<your api key>

.envrc

@@ -0,0 +1,26 @@
+# direnv file
+
+# This is just a bash script.
+# https://direnv.net/man/direnv-stdlib.1.html
+# https://github.com/direnv/direnv/wiki
+
+# Activate the virtualenv
+# This simply replicates what venv/bin/activate does.
+# See, https://docs.python.org/3/library/venv.html#module-venv
+
+if [[ -d ".venv/bin" ]]; then
+    # The path to the virtualenv should be absolute. If you use ipython
+    # for the Django shell it will raise an error if the path is relative.
+    # https://github.com/ipython/ipython/issues/13268
+    # https://github.com/direnv/direnv/issues/304
+    export VIRTUAL_ENV=`pwd`/.venv
+    PATH_add ".venv/bin"
+fi
+
+# Set environment variables from .env. We're using a conditional
+# in case an older version of direnv is used. In recent releases
+# there is the stdlib function dotenv_if_exists
+
+if [[ -f ".env" ]]; then
+    dotenv
+fi

.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[co]
+*.egg*
+
+# Editor temp files
+*~
+
+# Ignore dot files except those required for the project
+.*
+!.editorconfig
+!.env.example
+!.envrc
+!.gitignore
+!.gitkeep
+!.pre-commit-config.yaml
+!.readthedocs.yaml
+
+# data
+*.sqlite3
+*.csv
+
+!ebird_basic_dataset_sample.csv
+!MyEBirdData.csv
+
+#docs
+_build/
+
+# directories
+logs/

.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v3.2.0
+  hooks:
+  -   id: trailing-whitespace
+  -   id: end-of-file-fixer
+  -   id: check-yaml
+  -   id: check-added-large-files
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.8.0
+  hooks:
+    # Run the linter.
+    - id: ruff
+      types_or: [ python, pyi ]
+      args: [ --fix ]
+    # Run the formatter.
+    - id: ruff-format
+      types_or: [ python, pyi ]
+- repo: https://github.com/pycqa/isort
+  rev: 5.12.0
+  hooks:
+    - id: isort

.readthedocs.yaml

@@ -0,0 +1,23 @@
+# This file is part of the django-environ.
+#
+# Copyright (c) 2024, Stuart MacKay <smackay@flagstonesoftware.com>
+#
+# For the full copyright and license information, please view
+# the LICENSE file that was distributed with this source code.
+
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+---
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: '3.12'
+  commands:
+    - asdf plugin add uv
+    - asdf install uv latest
+    - asdf global uv latest
+    - uv sync --extra docs --frozen
+    - uv run -m sphinx -T -b html -d docs/_build/doctrees -D language=en docs $READTHEDOCS_OUTPUT/html

CHANGELOG.rst

@@ -0,0 +1,12 @@
+Changelog
+=========
+All notable changes to this project will be documented in this file.
+The format is inspired by `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_
+and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
+
+Unreleased
+-------------------
+Added
+^^^^^
+Initial release with loaders and models for the database and a Django Admin module
+for viewing the data downloaded from eBird.

CITATION.cff

@@ -0,0 +1,17 @@
+abstract:
+    eBird Checklists is are usable Django app for loading data from eBird
+    into a database.
+authors:
+  - name: Stuart MacKay
+cff-version: 1.2.0
+date-released: 2024-12-01
+keywords:
+  - checklists
+  - Django
+  - eBird
+  - models
+license: MIT License
+message: If you use this software, please cite it using the metadata from this file.
+repository-code: "https://github.com/StuartMacKay/ebird-checklists"
+title: eBird Checklists
+version: 0.0.0

LICENSE

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

README.rst

@@ -0,0 +1,139 @@
+eBird Checklists
+================
+eBird Checklists is a reusable Django app for loading data from eBird into a database.
+
+Overview
+--------
+.. overview-start
+
+Observations submitted to eBird are available from three sources:
+
+1. The `eBird Basic Dataset`_
+2. Records from `Download My Data`_ in your eBird account
+3. Records downloaded from the `eBird API 2.0`_
+
+This project contains loaders and models to take data from each of these
+sources and load it into a database. The models also have custom QuerySets
+which implement the most common queries, providing an easy to use API for
+accessing the data.
+
+.. _eBird Basic Dataset: https://support.ebird.org/en/support/solutions/articles/48000838205-download-ebird-data#anchorEBD
+.. _Download My Data: https://ebird.org/downloadMyData
+.. _eBird API 2.0: https://documenter.getpostman.com/view/664302/S1ENwy59
+
+.. 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-checklists
+
+or:
+
+.. code-block:: console
+
+    uv add ebird-checklists
+
+Update ``INSTALLED_APPS`` in your Django setting:
+
+.. code-block:: python
+
+    INSTALLED_APPS = [
+        ...
+        ebird.checklists
+    ]
+
+Finally, run the migrations to create the tables:
+
+.. code-block:: python
+
+    python manage.py migrate
+
+Everything is now ready to load data from one of the sources above. The
+project documentation has detailed instructions in the ``Loading Data``
+section. Please see 'Project Information' below.
+
+.. _pip: https://pip.pypa.io/en/stable/
+.. _uv: https://docs.astral.sh/uv/
+.. _package: https://pypi.org/project/ebird-checklists/
+
+.. install-end
+
+Demo
+----
+
+.. demo-start
+
+If you check out the code from the repository there is a fully functioning
+Django site, and a sample data file for the eBird Basic Dataset, that you
+can use to see the app in action.
+
+.. code-block:: console
+
+    git clone git@github.com:StuartMacKay/ebird-checklists.git
+    cd ebird-checklists
+
+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
+
+Load the sample data from the eBird Basic Dataset:
+
+.. code-block:: console
+
+    python manage.py load_csv data/downloads/ebird_basic_dataset_sample.csv
+
+Create a user:
+
+.. code-block:: console
+
+    python manage.py createsuperuser
+
+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-checklists.readthedocs.io/en/latest/
+* Issues: https://github.com/StuartMacKay/ebird-checklists/issues
+* Repository: https://github.com/StuartMacKay/ebird-checklists
+
+The app is tested on Python 3.8+, and officially supports Django 4.2, 5.0 and 5.1.
+
+eBird Checklists is released under the terms of the `MIT`_ license.
+
+.. _MIT: https://opensource.org/licenses/MIT