ebird-api 3.0.7__tar.gz → 3.1.0__tar.gz

{ebird_api-3.0.7 → ebird_api-3.1.0}/CHANGELOG.md

@@ -1,13 +1,18 @@
 # Change Log
 All notable changes to this project will be documented in this file.
-Only changes for the API functions are described here. Changes made 
-to the internals and developing the package are not included. Check 
+Only changes for the API functions are described here. Changes made
+to the internals and developing the package are not included. Check
 the git log for details.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/).
 This project adheres to [PEP440](https://www.python.org/dev/peps/pep-0440/)
 and by implication, [Semantic Versioning](http://semver.org/).
 
+## [3.1.0] - 2024-12-30
+### Added
+- get_taxonomy_locales which returns a list of all the languages
+  supported for species common names.
+
 ## [3.0.7] - 2024-10-09
 ### Changed
 - get_taxonomy now passes "locale" as a parameter, not "sppLocale",
@@ -16,40 +21,40 @@ and by implication, [Semantic Versioning](http://semver.org/).
 ## [3.0.6] - 2020-09-09
 ### Changed
 - Subnational1 and subnational2 codes were assumed to be at least two
-  characters. Now they are at least 1 character. 
+  characters. Now they are at least 1 character.
 
 ## [3.0.5] - 2019-08-31
 ### Changed
-- Replaced the checklistSort query parameter for the top_100 end-point 
+- Replaced the checklistSort query parameter for the top_100 end-point
   with rankedBy. This change was made by eBird as checklistSort was not
   working.
 
 ## [3.0.4] - 2019-07-22
 ### Changed
-- Update the functions for fetching observations to use the sppLocale 
+- Update the functions for fetching observations to use the sppLocale
   query parameter to match the recent changes made in the eBird API.
 
 ## [3.0.3] - 2019-07-16
 ### Changed
 - When fetching observations, the list of area may only contain 10 items.
-  Previously more than 10 were allowed but this was a bug and was fixed to 
-  limit the load on the server. 
+  Previously more than 10 were allowed but this was a bug and was fixed to
+  limit the load on the server.
 
 ## [3.0.2] - 2019-06-22
 ### Changed
-- Updated the validation check for region codes so it supports ISO 3166-2. 
-- Disabled the validation check that limited the number of areas to 10 as 
+- Updated the validation check for region codes so it supports ISO 3166-2.
+- Disabled the validation check that limited the number of areas to 10 as
   the eBird API does not currently enforce this.
 
 ## [3.0.1] - 2019-06-15
-### Added 
+### Added
 - Added the full list of locales support by eBird (but not necessarily by the API).
 - Added a convenience function for saving downloaded records to a file.
 ### Changed
 - Validating the locale now uses the list supported by eBird.
 
 ## [3.0.0] - 2019-06-06
-### Added 
+### Added
 - Rewritten to support eBird API 2.0
 
 ## [2.1.1] - 2019-05-14
@@ -61,31 +66,31 @@ and by implication, [Semantic Versioning](http://semver.org/).
 - Improved the documentation in the README.
 - Project now uses the MIT license.
 
-### Added 
+### Added
 - Added scripts so each API call can be made on the command line.
 
 ## [2.0.0] - 2017-02-27
-### Changed 
+### Changed
 - Moved all the functions into the 'api' module and changed the top-level
 'ebird' module to be namespaced (PEP420).
 
 ## [1.0.2] - 2017-02-23
-### Changed 
+### Changed
 - Corrected version number in python.
 
 ## [1.0.1] - 2017-02-21
-### Added 
+### Added
 - Updated docstrings to report exceptions raised.
 
 ## [1.0.0] - 2017-02-21
-### Added 
+### Added
 - Added function for Google Gadgets showing recent observations.
 - Added function for fetching lists of species.
 - Added function for fetching nearby hotspots.
 - Added function for fetching lists of hotspots for a region.
 ### Changed
-- Renamed list_locations() to list_regions() and find_locations() to 
-find_regions() as "locations" refer to specific sites in the functions 
+- Renamed list_locations() to list_regions() and find_locations() to
+find_regions() as "locations" refer to specific sites in the functions
 that fetch observations.
 
 ## [0.2.0] - 2017-02-18

{ebird_api-3.0.7/src/ebird_api.egg-info → ebird_api-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ebird-api
-Version: 3.0.7
+Version: 3.1.0
 Summary: Wrapper for accessing the eBird API
 Author-email: Project Babbler <projectbabbler@gmail.com>
 License: MIT License
@@ -68,19 +68,25 @@ what you want to do - they will be interested to hear it.
 ### Observations
 
 ```python
+import os
+
 from ebird.api import get_observations
+
+# Always store secrets outside the code, so you don't accidentally
+# commit them. Environment variables are ideal for this.
+api_key = os.environ["EBIRD_API_KEY"]
     
 # Get observations from Woodman Pond, Madison county, New York for the past week.
-records = get_observations(api_key, 'L227544', back=7)
+this_week = get_observations(api_key, 'L227544', back=7)
 
 # Get observations from Madison county, New York
-records = get_observations(api_key, 'US-NY-053')
+country_records = get_observations(api_key, 'US-NY-053')
 
 # Get observations from New York
-records = get_observations(api_key, 'US-NY')
+state_records = get_observations(api_key, 'US-NY')
 
 # Get observations from the USA - don't overdo the data downloads
-records = get_observations(api_key, 'US')
+national_records = get_observations(api_key, 'US')
 ```
 
 Any where you pass in single location or region you can also pass in a 
@@ -88,8 +94,12 @@ list or a comma-separated string. You can specify up to 10 locations or
 regions:
 
 ```python
+import os
+
 from ebird.api import get_observations
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get the observations for the most visited locations in Madison county, New York:
 # Woodman Pond, Ditch Bank Rd., Cornell Biological Field Station and
 # Anne V Pickard Memorial Wildlife Overlook.
@@ -101,11 +111,17 @@ counties = 'US-NY-103,US-NY-059,US-NY-81'
 records = get_observations(api_key, locations, hotspot=False, category='species')
 ```
 
-The common name for species can be returned in different languages by specifying locale in the functions that return observations, checklists or taxonomy:
+The common name for species can be returned in different languages by 
+specifying locale in the functions that return observations, checklists 
+or taxonomy:
 
 ```python
+import os
+
 from ebird.api import get_observations
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 records = get_observations(api_key, 'CA-QC', locale='fr')
 ```
 
@@ -115,8 +131,12 @@ geographical area - useful for finding the nearest place to see a given
 species:
 
 ```python
+import os
+
 from ebird.api import get_nearby_observations
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get the most recent sightings of all species seen in the last week within 
 # 10km of Point Reyes National Seashore.
 records = get_nearby_observations(api_key, 38.05, -122.94, dist=10, back=7)
@@ -128,30 +148,42 @@ notable ones (locally or nationally rare species) or limit the records to
 a small number of species:
 
 ```python
-from ebird.api import get_notable_observations, get_nearby_notable, \
-    get_species_observations, get_nearby_species
+import os
+
+from ebird.api import (
+    get_notable_observations, 
+    get_nearby_notable,
+    get_species_observations, 
+    get_nearby_species,
+)
+
+api_key = os.environ["EBIRD_API_KEY"]
 
 # Get the interesting birds seen in New York state.
-records = get_notable_observations(api_key, 'US-NY')
+notables = get_notable_observations(api_key, 'US-NY')
 
 # Get the observations of Horned Lark (Eremophila alpestris) in New York state.
 records = get_species_observations(api_key, 'horlar', 'US-NY')
 
 # Get the interesting birds within 50kn of Point Reyes
-records = get_nearby_notable(api_key, 38.05, -122.94, dist=50)
+nearby_notables = get_nearby_notable(api_key, 38.05, -122.94, dist=50)
 
 # Find out if Barn Swallows have been seen in the area in the past 10 days
-records = get_nearby_species(api_key, 'barswa', 38.05, -122.94, back=10)
+nearby_species = get_nearby_species(api_key, 'barswa', 38.05, -122.94, back=10)
 ```
 
 For the more travel-minded you can also find out the nearest place to see a given species:
 
 ```python
+import os 
+
 from ebird.api import get_nearest_species
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Where is the closest place to Cornell Lab of Ornithology to see
 # Tennessee Warbler. 
-locations = get_nearest_species('tenwar', 42.48, -76.45)
+locations = get_nearest_species(api_key, 'tenwar', 42.48, -76.45)
 ```
 
 Depending on what time of year you try this, you might have a long way to go.
@@ -164,13 +196,17 @@ using get_visits(). Each result returned has the unique identifier for the
 checklist. You can then call get_checklist() to get the list of observations.
 
 ```python
+import os
+
 from ebird.api import get_visits, get_checklist
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get visits made recently to locations in New York state:
-records = get_visits(api_key, 'US-NY')
+visits = get_visits(api_key, 'US-NY')
 
 # Get visits made recently to locations in New York state on Jan 1st 2010
-records = get_visits(api_key, 'US-NY', '2010-01-01')
+recent_visits = get_visits(api_key, 'US-NY', '2010-01-01')
 
 # Get the details of a checklist
 checklist = get_checklist(api_key, 'S22536787')
@@ -185,17 +221,18 @@ hotspots within a given radius. get_hotspot() can be used to get information
 on the location of a given hotspot.
 
 ```python
+import os
+
 from ebird.api import get_hotspots, get_nearby_hotspots, get_hotspot
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # List all the hotspots in New York state.
 hotspots = get_hotspots(api_key, 'US-NY')
 
 # List all the hotspots in New York state visited in the past week.
 recent = get_hotspots(api_key, 'US-NY', back=7)
 
-# List all the hotspots in New York state visited in the past week.
-recent = get_hotspots(api_key, 'US-NY', back=7)
-
 # List all the hotspots in within 50kn of Point Reyes
 nearby = get_nearby_hotspots(api_key, 38.05, -122.94, dist=50)
 
@@ -211,8 +248,12 @@ list of sub-regions for a given region. For the approximate area covered
 by a region use get_region().
 
 ```python
+import os
+
 from ebird.api import get_regions, get_adjacent_regions, get_region
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get the list of countries in the world.
 countries = get_regions(api_key, 'country', 'world')
 
@@ -238,8 +279,12 @@ e.g. horlar (Horned Lark), cangoo (Canada Goose), etc.,
 that are used in the other API calls.
 
 ```python
+import os
+
 from ebird.api import get_taxonomy, get_taxonomy_forms, get_taxonomy_versions
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get all the species in the eBird taxonomy.
 taxonomy = get_taxonomy(api_key)
 
@@ -266,9 +311,13 @@ just for a specific day so it is really only useful for "Big Days" when
 lots of people are out trying to get the greatest number of species.
 
 ```python
+import os
+
 from datetime import date
 from ebird.api import get_top_100, get_totals
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get the winner of the Global Big Day in New York, on 5th May 2018
 winners = get_top_100(api_key, 'US-NY', '2018-05-05')
 
@@ -283,9 +332,11 @@ You can set the API key and locale when creating a Client instance so you don't
 have to keep passing them as arguments.
 
 ```python
+import os
+
 from ebird.api import Client
 
-api_key = 'abc123'
+api_key = os.environ["EBIRD_API_KEY"]
 locale = 'es'
 
 client = Client(api_key, locale)
@@ -305,7 +356,9 @@ only returns JSON.
 
 ## Compatibility
 
-ebird-api works with Python 3.5+. 
+ebird-api works with currently supported versions of Python, 3.8+. However, 
+it is known to work with earlier versions, at least 3.5 - 3.7, without any 
+problems.
 
 ## Links
 

{ebird_api-3.0.7 → ebird_api-3.1.0}/README.md

@@ -38,19 +38,25 @@ what you want to do - they will be interested to hear it.
 ### Observations
 
 ```python
+import os
+
 from ebird.api import get_observations
+
+# Always store secrets outside the code, so you don't accidentally
+# commit them. Environment variables are ideal for this.
+api_key = os.environ["EBIRD_API_KEY"]
     
 # Get observations from Woodman Pond, Madison county, New York for the past week.
-records = get_observations(api_key, 'L227544', back=7)
+this_week = get_observations(api_key, 'L227544', back=7)
 
 # Get observations from Madison county, New York
-records = get_observations(api_key, 'US-NY-053')
+country_records = get_observations(api_key, 'US-NY-053')
 
 # Get observations from New York
-records = get_observations(api_key, 'US-NY')
+state_records = get_observations(api_key, 'US-NY')
 
 # Get observations from the USA - don't overdo the data downloads
-records = get_observations(api_key, 'US')
+national_records = get_observations(api_key, 'US')
 ```
 
 Any where you pass in single location or region you can also pass in a 
@@ -58,8 +64,12 @@ list or a comma-separated string. You can specify up to 10 locations or
 regions:
 
 ```python
+import os
+
 from ebird.api import get_observations
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get the observations for the most visited locations in Madison county, New York:
 # Woodman Pond, Ditch Bank Rd., Cornell Biological Field Station and
 # Anne V Pickard Memorial Wildlife Overlook.
@@ -71,11 +81,17 @@ counties = 'US-NY-103,US-NY-059,US-NY-81'
 records = get_observations(api_key, locations, hotspot=False, category='species')
 ```
 
-The common name for species can be returned in different languages by specifying locale in the functions that return observations, checklists or taxonomy:
+The common name for species can be returned in different languages by 
+specifying locale in the functions that return observations, checklists 
+or taxonomy:
 
 ```python
+import os
+
 from ebird.api import get_observations
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 records = get_observations(api_key, 'CA-QC', locale='fr')
 ```
 
@@ -85,8 +101,12 @@ geographical area - useful for finding the nearest place to see a given
 species:
 
 ```python
+import os
+
 from ebird.api import get_nearby_observations
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get the most recent sightings of all species seen in the last week within 
 # 10km of Point Reyes National Seashore.
 records = get_nearby_observations(api_key, 38.05, -122.94, dist=10, back=7)
@@ -98,30 +118,42 @@ notable ones (locally or nationally rare species) or limit the records to
 a small number of species:
 
 ```python
-from ebird.api import get_notable_observations, get_nearby_notable, \
-    get_species_observations, get_nearby_species
+import os
+
+from ebird.api import (
+    get_notable_observations, 
+    get_nearby_notable,
+    get_species_observations, 
+    get_nearby_species,
+)
+
+api_key = os.environ["EBIRD_API_KEY"]
 
 # Get the interesting birds seen in New York state.
-records = get_notable_observations(api_key, 'US-NY')
+notables = get_notable_observations(api_key, 'US-NY')
 
 # Get the observations of Horned Lark (Eremophila alpestris) in New York state.
 records = get_species_observations(api_key, 'horlar', 'US-NY')
 
 # Get the interesting birds within 50kn of Point Reyes
-records = get_nearby_notable(api_key, 38.05, -122.94, dist=50)
+nearby_notables = get_nearby_notable(api_key, 38.05, -122.94, dist=50)
 
 # Find out if Barn Swallows have been seen in the area in the past 10 days
-records = get_nearby_species(api_key, 'barswa', 38.05, -122.94, back=10)
+nearby_species = get_nearby_species(api_key, 'barswa', 38.05, -122.94, back=10)
 ```
 
 For the more travel-minded you can also find out the nearest place to see a given species:
 
 ```python
+import os 
+
 from ebird.api import get_nearest_species
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Where is the closest place to Cornell Lab of Ornithology to see
 # Tennessee Warbler. 
-locations = get_nearest_species('tenwar', 42.48, -76.45)
+locations = get_nearest_species(api_key, 'tenwar', 42.48, -76.45)
 ```
 
 Depending on what time of year you try this, you might have a long way to go.
@@ -134,13 +166,17 @@ using get_visits(). Each result returned has the unique identifier for the
 checklist. You can then call get_checklist() to get the list of observations.
 
 ```python
+import os
+
 from ebird.api import get_visits, get_checklist
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get visits made recently to locations in New York state:
-records = get_visits(api_key, 'US-NY')
+visits = get_visits(api_key, 'US-NY')
 
 # Get visits made recently to locations in New York state on Jan 1st 2010
-records = get_visits(api_key, 'US-NY', '2010-01-01')
+recent_visits = get_visits(api_key, 'US-NY', '2010-01-01')
 
 # Get the details of a checklist
 checklist = get_checklist(api_key, 'S22536787')
@@ -155,17 +191,18 @@ hotspots within a given radius. get_hotspot() can be used to get information
 on the location of a given hotspot.
 
 ```python
+import os
+
 from ebird.api import get_hotspots, get_nearby_hotspots, get_hotspot
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # List all the hotspots in New York state.
 hotspots = get_hotspots(api_key, 'US-NY')
 
 # List all the hotspots in New York state visited in the past week.
 recent = get_hotspots(api_key, 'US-NY', back=7)
 
-# List all the hotspots in New York state visited in the past week.
-recent = get_hotspots(api_key, 'US-NY', back=7)
-
 # List all the hotspots in within 50kn of Point Reyes
 nearby = get_nearby_hotspots(api_key, 38.05, -122.94, dist=50)
 
@@ -181,8 +218,12 @@ list of sub-regions for a given region. For the approximate area covered
 by a region use get_region().
 
 ```python
+import os
+
 from ebird.api import get_regions, get_adjacent_regions, get_region
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get the list of countries in the world.
 countries = get_regions(api_key, 'country', 'world')
 
@@ -208,8 +249,12 @@ e.g. horlar (Horned Lark), cangoo (Canada Goose), etc.,
 that are used in the other API calls.
 
 ```python
+import os
+
 from ebird.api import get_taxonomy, get_taxonomy_forms, get_taxonomy_versions
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get all the species in the eBird taxonomy.
 taxonomy = get_taxonomy(api_key)
 
@@ -236,9 +281,13 @@ just for a specific day so it is really only useful for "Big Days" when
 lots of people are out trying to get the greatest number of species.
 
 ```python
+import os
+
 from datetime import date
 from ebird.api import get_top_100, get_totals
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get the winner of the Global Big Day in New York, on 5th May 2018
 winners = get_top_100(api_key, 'US-NY', '2018-05-05')
 
@@ -253,9 +302,11 @@ You can set the API key and locale when creating a Client instance so you don't
 have to keep passing them as arguments.
 
 ```python
+import os
+
 from ebird.api import Client
 
-api_key = 'abc123'
+api_key = os.environ["EBIRD_API_KEY"]
 locale = 'es'
 
 client = Client(api_key, locale)
@@ -275,7 +326,9 @@ only returns JSON.
 
 ## Compatibility
 
-ebird-api works with Python 3.5+. 
+ebird-api works with currently supported versions of Python, 3.8+. However, 
+it is known to work with earlier versions, at least 3.5 - 3.7, without any 
+problems.
 
 ## Links
 

ebird_api-3.1.0/pyproject.toml

@@ -0,0 +1,127 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = ["setuptools >= 61.0"]
+
+[project]
+authors = [
+  {name = "Project Babbler", email = "projectbabbler@gmail.com"},
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Natural Language :: English",
+    "Topic :: Utilities",
+    "Topic :: Internet",
+]
+description = 'Wrapper for accessing the eBird API'
+keywords = ["eBird", "API", "client"]
+license = {text = "MIT License"}
+name = "ebird-api"
+readme = "README.md"
+requires-python = ">= 3.8"
+version = "3.1.0"
+
+[project.urls]
+Repository = "https://github.com/ProjectBabbler/ebird-api.git"
+Issues = "https://github.com/ProjectBabbler/ebird-api/issues"
+Changelog = "https://github.com/ProjectBabbler/ebird-api/blob/master/CHANGELOG.md"
+
+[tool.bumpversion]
+current_version = "3.1.0"
+parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
+serialize = ["{major}.{minor}.{patch}"]
+ignore_missing_version = false
+tag = true
+sign_tags = true
+tag_name = "v{new_version}"
+tag_message = "New version: {current_version} → {new_version}"
+allow_dirty = false
+commit = true
+message = "New version: {current_version} → {new_version}"
+commit_args = ""
+
+[[tool.bumpversion.files]]
+filename = "src/ebird/api/__init__.py"
+search = '__version__ = "{current_version}"'
+replace = '__version__ = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "CHANGELOG.md"
+search = "## [Unreleased]"
+replace = "## [{new_version}] - {now:%Y-%m-%d}"
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "CITATION.cff"
+search = "version: {current_version}"
+replace = "version: {new_version}"
+
+[[tool.bumpversion.files]]
+filename = "CITATION.cff"
+search = "^date-released: \\d{{4}}-\\d{{2}}-\\d{{2}}$"
+replace = "date-released: {now:%Y-%m-%d}"
+regex = true
+
+[tool.coverage.run]
+branch = true
+
+[tool.isort]
+multi_line_output = 3
+include_trailing_comma = true
+
+[tool.pytest.ini_options]
+pythonpath = [
+  "."
+]
+testpaths = [
+    "tests/unit"
+]
+
+[tool.tox]
+legacy_tox_ini = """
+[tox]
+requires =
+    tox>=4.2
+    tox-uv>=1.11.3
+envlist = py38, py39, py310, py311, py312
+
+[testenv]
+commands = pytest
+deps =
+    pytest
+setenv =
+    PYTHONPATH = src
+"""
+
+[tool.uv]
+dev-dependencies = [
+    "bump-my-version>=0.28.0",
+    "coverage>=7.6.1",
+    "flake8>=5.0.4",
+    "geopy>=2.4.1",
+    "isort>=5.13.2",
+    "pytest>=8.3.3",
+    "pytest-cov>=5.0.0",
+    "tox>=4.23.1",
+    "tox-uv>=1.11.3",
+    "pre-commit>=3.5.0",
+    "ruff>=0.8.0",
+]
+
+[tool.uv.sources]
+ebird-api = { workspace = true }

{ebird_api-3.0.7 → ebird_api-3.1.0}/src/ebird/api/__init__.py

@@ -2,7 +2,7 @@
 
 """A set of wrapper functions for accessing the eBird API."""
 
-__version__ = "3.0.7"
+__version__ = "3.1.0"
 
 from ebird.api.checklists import get_checklist, get_visits
 from ebird.api.client import Client
@@ -24,5 +24,6 @@ from ebird.api.taxonomy import (
     get_taxonomy,
     get_taxonomy_forms,
     get_taxonomy_groups,
+    get_taxonomy_locales,
     get_taxonomy_versions,
 )

{ebird_api-3.0.7 → ebird_api-3.1.0}/src/ebird/api/client.py

@@ -2,7 +2,14 @@
 
 """Classes for simplifying calls to the eBird API."""
 
-from ebird.api import checklists, hotspots, observations, regions, statistics, taxonomy
+from ebird.api import (
+    checklists,
+    hotspots,
+    observations,
+    regions,
+    statistics,
+    taxonomy,
+)
 from ebird.api.validation import clean_locale
 
 

{ebird_api-3.0.7 → ebird_api-3.1.0}/src/ebird/api/hotspots.py

@@ -21,7 +21,7 @@ def get_hotspots(token, region, back=None):
     If back is specified then only the hotspots visited in the given number
     of days are returned.
 
-    Fetch all the hotspots visited in  country, subnational1 or subnational2
+    Fetch all the hotspots visited in a country, subnational1 or subnational2
     area recently (up to 30 days ago).
 
     This maps to the end point in the eBird API 2.0,

{ebird_api-3.0.7 → ebird_api-3.1.0}/src/ebird/api/taxonomy.py

@@ -13,6 +13,7 @@ TAXONOMY_URL = "https://ebird.org/ws2.0/ref/taxonomy/ebird"
 TAXONOMY_FORMS_URL = "https://ebird.org/ws2.0/ref/taxon/forms/%s"
 TAXONOMY_GROUPS_URL = "https://ebird.org/ws2.0/ref/sppgroup/%s"
 TAXONOMY_VERSIONS_URL = "https://ebird.org/ws2.0/ref/taxonomy/versions"
+TAXONOMY_LOCALES_URL = "https://api.ebird.org/v2/ref/taxa-locales/ebird"
 
 
 def get_taxonomy(token, category=None, locale="en", version=None, species=None):
@@ -180,3 +181,33 @@ def get_taxonomy_versions(token):
     }
 
     return call(TAXONOMY_VERSIONS_URL, {}, headers)
+
+
+def get_taxonomy_locales(token):
+    """Get all locales supported for common names.
+
+    The maps to the end point in the eBird API 2.0,
+    https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#3ea8ff71-c254-4811-9e80-b445a39302a6
+
+    This API call returns a list of all the languages supported
+    by eBird. An entry in the list takes the form:
+
+        {'code': 'af', 'lastUpdate': '2024-12-21 06:06', 'name': 'Afrikaans'}
+
+    There are currently, (2024-12-30), 107 languages available.
+
+    :param token: the token needed to access the API.
+
+    :return: a list of all the taxonomy locales used by eBird.
+
+    :raises URLError if there is an error with the connection to the
+    eBird site.
+
+    :raises HTTPError if the eBird API returns an error.
+
+    """
+    headers = {
+        "X-eBirdApiToken": token,
+    }
+
+    return call(TAXONOMY_LOCALES_URL, {}, headers)

{ebird_api-3.0.7 → ebird_api-3.1.0/src/ebird_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ebird-api
-Version: 3.0.7
+Version: 3.1.0
 Summary: Wrapper for accessing the eBird API
 Author-email: Project Babbler <projectbabbler@gmail.com>
 License: MIT License
@@ -68,19 +68,25 @@ what you want to do - they will be interested to hear it.
 ### Observations
 
 ```python
+import os
+
 from ebird.api import get_observations
+
+# Always store secrets outside the code, so you don't accidentally
+# commit them. Environment variables are ideal for this.
+api_key = os.environ["EBIRD_API_KEY"]
     
 # Get observations from Woodman Pond, Madison county, New York for the past week.
-records = get_observations(api_key, 'L227544', back=7)
+this_week = get_observations(api_key, 'L227544', back=7)
 
 # Get observations from Madison county, New York
-records = get_observations(api_key, 'US-NY-053')
+country_records = get_observations(api_key, 'US-NY-053')
 
 # Get observations from New York
-records = get_observations(api_key, 'US-NY')
+state_records = get_observations(api_key, 'US-NY')
 
 # Get observations from the USA - don't overdo the data downloads
-records = get_observations(api_key, 'US')
+national_records = get_observations(api_key, 'US')
 ```
 
 Any where you pass in single location or region you can also pass in a 
@@ -88,8 +94,12 @@ list or a comma-separated string. You can specify up to 10 locations or
 regions:
 
 ```python
+import os
+
 from ebird.api import get_observations
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get the observations for the most visited locations in Madison county, New York:
 # Woodman Pond, Ditch Bank Rd., Cornell Biological Field Station and
 # Anne V Pickard Memorial Wildlife Overlook.
@@ -101,11 +111,17 @@ counties = 'US-NY-103,US-NY-059,US-NY-81'
 records = get_observations(api_key, locations, hotspot=False, category='species')
 ```
 
-The common name for species can be returned in different languages by specifying locale in the functions that return observations, checklists or taxonomy:
+The common name for species can be returned in different languages by 
+specifying locale in the functions that return observations, checklists 
+or taxonomy:
 
 ```python
+import os
+
 from ebird.api import get_observations
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 records = get_observations(api_key, 'CA-QC', locale='fr')
 ```
 
@@ -115,8 +131,12 @@ geographical area - useful for finding the nearest place to see a given
 species:
 
 ```python
+import os
+
 from ebird.api import get_nearby_observations
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get the most recent sightings of all species seen in the last week within 
 # 10km of Point Reyes National Seashore.
 records = get_nearby_observations(api_key, 38.05, -122.94, dist=10, back=7)
@@ -128,30 +148,42 @@ notable ones (locally or nationally rare species) or limit the records to
 a small number of species:
 
 ```python
-from ebird.api import get_notable_observations, get_nearby_notable, \
-    get_species_observations, get_nearby_species
+import os
+
+from ebird.api import (
+    get_notable_observations, 
+    get_nearby_notable,
+    get_species_observations, 
+    get_nearby_species,
+)
+
+api_key = os.environ["EBIRD_API_KEY"]
 
 # Get the interesting birds seen in New York state.
-records = get_notable_observations(api_key, 'US-NY')
+notables = get_notable_observations(api_key, 'US-NY')
 
 # Get the observations of Horned Lark (Eremophila alpestris) in New York state.
 records = get_species_observations(api_key, 'horlar', 'US-NY')
 
 # Get the interesting birds within 50kn of Point Reyes
-records = get_nearby_notable(api_key, 38.05, -122.94, dist=50)
+nearby_notables = get_nearby_notable(api_key, 38.05, -122.94, dist=50)
 
 # Find out if Barn Swallows have been seen in the area in the past 10 days
-records = get_nearby_species(api_key, 'barswa', 38.05, -122.94, back=10)
+nearby_species = get_nearby_species(api_key, 'barswa', 38.05, -122.94, back=10)
 ```
 
 For the more travel-minded you can also find out the nearest place to see a given species:
 
 ```python
+import os 
+
 from ebird.api import get_nearest_species
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Where is the closest place to Cornell Lab of Ornithology to see
 # Tennessee Warbler. 
-locations = get_nearest_species('tenwar', 42.48, -76.45)
+locations = get_nearest_species(api_key, 'tenwar', 42.48, -76.45)
 ```
 
 Depending on what time of year you try this, you might have a long way to go.
@@ -164,13 +196,17 @@ using get_visits(). Each result returned has the unique identifier for the
 checklist. You can then call get_checklist() to get the list of observations.
 
 ```python
+import os
+
 from ebird.api import get_visits, get_checklist
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get visits made recently to locations in New York state:
-records = get_visits(api_key, 'US-NY')
+visits = get_visits(api_key, 'US-NY')
 
 # Get visits made recently to locations in New York state on Jan 1st 2010
-records = get_visits(api_key, 'US-NY', '2010-01-01')
+recent_visits = get_visits(api_key, 'US-NY', '2010-01-01')
 
 # Get the details of a checklist
 checklist = get_checklist(api_key, 'S22536787')
@@ -185,17 +221,18 @@ hotspots within a given radius. get_hotspot() can be used to get information
 on the location of a given hotspot.
 
 ```python
+import os
+
 from ebird.api import get_hotspots, get_nearby_hotspots, get_hotspot
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # List all the hotspots in New York state.
 hotspots = get_hotspots(api_key, 'US-NY')
 
 # List all the hotspots in New York state visited in the past week.
 recent = get_hotspots(api_key, 'US-NY', back=7)
 
-# List all the hotspots in New York state visited in the past week.
-recent = get_hotspots(api_key, 'US-NY', back=7)
-
 # List all the hotspots in within 50kn of Point Reyes
 nearby = get_nearby_hotspots(api_key, 38.05, -122.94, dist=50)
 
@@ -211,8 +248,12 @@ list of sub-regions for a given region. For the approximate area covered
 by a region use get_region().
 
 ```python
+import os
+
 from ebird.api import get_regions, get_adjacent_regions, get_region
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get the list of countries in the world.
 countries = get_regions(api_key, 'country', 'world')
 
@@ -238,8 +279,12 @@ e.g. horlar (Horned Lark), cangoo (Canada Goose), etc.,
 that are used in the other API calls.
 
 ```python
+import os
+
 from ebird.api import get_taxonomy, get_taxonomy_forms, get_taxonomy_versions
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get all the species in the eBird taxonomy.
 taxonomy = get_taxonomy(api_key)
 
@@ -266,9 +311,13 @@ just for a specific day so it is really only useful for "Big Days" when
 lots of people are out trying to get the greatest number of species.
 
 ```python
+import os
+
 from datetime import date
 from ebird.api import get_top_100, get_totals
 
+api_key = os.environ["EBIRD_API_KEY"]
+
 # Get the winner of the Global Big Day in New York, on 5th May 2018
 winners = get_top_100(api_key, 'US-NY', '2018-05-05')
 
@@ -283,9 +332,11 @@ You can set the API key and locale when creating a Client instance so you don't
 have to keep passing them as arguments.
 
 ```python
+import os
+
 from ebird.api import Client
 
-api_key = 'abc123'
+api_key = os.environ["EBIRD_API_KEY"]
 locale = 'es'
 
 client = Client(api_key, locale)
@@ -305,7 +356,9 @@ only returns JSON.
 
 ## Compatibility
 
-ebird-api works with Python 3.5+. 
+ebird-api works with currently supported versions of Python, 3.8+. However, 
+it is known to work with earlier versions, at least 3.5 - 3.7, without any 
+problems.
 
 ## Links
 

{ebird_api-3.0.7 → ebird_api-3.1.0}/src/ebird_api.egg-info/SOURCES.txt

@@ -1,6 +1,5 @@
 CHANGELOG.md
 LICENSE.txt
-MANIFEST.in
 README.md
 pyproject.toml
 setup.py

ebird_api-3.0.7/MANIFEST.in

@@ -1,2 +0,0 @@
-include CHANGELOG.md LICENSE.txt
-recursive-include src *.py

ebird_api-3.0.7/pyproject.toml

@@ -1,56 +0,0 @@
-[build-system]
-build-backend = "setuptools.build_meta"
-requires = ["setuptools >= 61.0"]
-
-[project]
-authors = [
-  {name = "Project Babbler", email = "projectbabbler@gmail.com"},
-]
-classifiers = [
-    "Development Status :: 5 - Production/Stable",
-    "Environment :: Console",
-    "Intended Audience :: Science/Research",
-    "License :: OSI Approved :: MIT License",
-    "Operating System :: OS Independent",
-    "Programming Language :: Python",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.8",
-    "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: Implementation :: CPython",
-    "Natural Language :: English",
-    "Topic :: Utilities",
-    "Topic :: Internet",
-]
-description = 'Wrapper for accessing the eBird API'
-keywords = ["eBird", "API", "client"]
-license = {text = "MIT License"}
-name = "ebird-api"
-readme = "README.md"
-requires-python = ">= 3.8"
-version = "3.0.7"
-
-[project.urls]
-Repository = "https://github.com/ProjectBabbler/ebird-api.git"
-Issues = "https://github.com/ProjectBabbler/ebird-api/issues"
-Changelog = "https://github.com/ProjectBabbler/ebird-api/blob/master/CHANGELOG.md"
-
-[tool.black]
-# Notes:
-#
-# line-length: this is just the default but it's included here so it's easy
-# to see that the value is synced with other code quality tools.
-#
-# target-version: the python version is set when the project is generated
-# so we might as well make use of it.
-#
-# exclude: the regex for excluding migrations is added in case you don't
-# want them reformatted.
-#
-# For all options see:
-#   https://black.readthedocs.io/en/stable/installation_and_usage.html
-
-line-length = 88
-target-version = ["py312"]