ebird-api 3.4.1__tar.gz → 4.0.0__tar.gz

{ebird_api-3.4.1 → ebird_api-4.0.0}/CHANGELOG.md

@@ -8,6 +8,14 @@ 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/).
 
+## [4.0.0] - 2025-07-09
+- Moved the package to ebird.api.requests to make space for other projects.
+- Changed the minimum supported python version to 3.10
+
+## [3.4.2] - 2025-04-05
+- Added a timeout so the client will raise an error if the connection
+  to eBird freezes
+
 ## [3.4.1] - 2025-02-12
 - Disallow lower case location codes
 

{ebird_api-3.4.1/src/ebird_api.egg-info → ebird_api-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: ebird-api
-Version: 3.4.1
+Version: 4.0.0
 Summary: Wrapper for accessing the eBird API
 Author-email: Project Babbler <projectbabbler@gmail.com>
 License: MIT License
@@ -15,27 +15,26 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 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: Programming Language :: Python :: Implementation :: CPython
 Classifier: Natural Language :: English
 Classifier: Topic :: Utilities
 Classifier: Topic :: Internet
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
+Dynamic: license-file
 
-[![Build Status](https://travis-ci.org/ProjectBabbler/ebird-api.svg?branch=master)](https://travis-ci.org/ProjectBabbler/ebird-api)
 [![PyPI version](https://badge.fury.io/py/ebird-api.svg)](https://badge.fury.io/py/ebird-api)
 [![Supported Python Versions](https://img.shields.io/pypi/pyversions/ebird-api.svg)](https://img.shields.io/pypi/pyversions/ebird-api)
 
 # eBird API
 
-eBird API provides a set of wrapper functions for accessing the end-points
-in the eBird API 2.0.
+eBird API Requests provides a set of wrapper functions for accessing the
+end-points in the eBird API 2.0.
 
 ## Install
 
@@ -46,23 +45,23 @@ pip install ebird-api
 ## Usage
 
 Each of the functions map to a specific end-point in the API - with one or
-two exceptions where API calls are essentially identical. The functions can 
-be grouped into five activities: fetching observations, getting information 
-on hotspots, getting information on regions, getting lists of species and 
+two exceptions where API calls are essentially identical. The functions can
+be grouped into five activities: fetching observations, getting information
+on hotspots, getting information on regions, getting lists of species and
 getting statistics.
 
-All functions support arguments (with sensible defaults) for all the query 
-parameters supported by the eBird API. Check the docstring for each function 
-for more details. There you will also find a link to the documentation for 
+All functions support arguments (with sensible defaults) for all the query
+parameters supported by the eBird API. Check the docstring for each function
+for more details. There you will also find a link to the documentation for
 each end-point.
 
-To use the API you will need to register for an API key. All you need to do is 
-fill out this [form](https://ebird.org/api/keygen) and the API key is generated 
+To use the API you will need to register for an API key. All you need to do is
+fill out this [form](https://ebird.org/api/keygen) and the API key is generated
 automatically.
 
-NOTE: Use the API with some restraint. Data costs money so don't go downloading 
-all the checklists for the world or other excessive behaviour or your account will 
-get banned. If you have a project in mind get in touch with eBird and tell them 
+NOTE: Use the API with some restraint. Data costs money so don't go downloading
+all the checklists for the world or other excessive behaviour or your account will
+get banned. If you have a project in mind get in touch with eBird and tell them
 what you want to do - they will be interested to hear it.
 
 ### Observations
@@ -70,12 +69,12 @@ what you want to do - they will be interested to hear it.
 ```python
 import os
 
-from ebird.api import get_observations
+from ebird.api.requests 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.
 this_week = get_observations(api_key, 'L227544', back=7)
 
@@ -89,14 +88,14 @@ state_records = get_observations(api_key, 'US-NY')
 national_records = get_observations(api_key, 'US')
 ```
 
-Any where you pass in single location or region you can also pass in a 
-list or a comma-separated string. You can specify up to 10 locations or 
+Any where you pass in single location or region you can also pass in a
+list or a comma-separated string. You can specify up to 10 locations or
 regions:
 
 ```python
 import os
 
-from ebird.api import get_observations
+from ebird.api.requests import get_observations
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -111,14 +110,14 @@ 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 
+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
+from ebird.api.requests import get_observations
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -126,34 +125,34 @@ records = get_observations(api_key, 'CA-QC', locale='fr')
 ```
 
 In addition to getting all the observations for a given location or in
-an area you can also get the latest observation of each species in a 
+an area you can also get the latest observation of each species in a
 geographical area - useful for finding the nearest place to see a given
 species:
 
 ```python
 import os
 
-from ebird.api import get_nearby_observations
+from ebird.api.requests 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 
+# 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)
 ```
 
-The calls to get_observations() and get_nearby_observation() return all the 
-available records. You can limit the set of records returned to only include 
-notable ones (locally or nationally rare species) or limit the records to 
+The calls to get_observations() and get_nearby_observation() return all the
+available records. You can limit the set of records returned to only include
+notable ones (locally or nationally rare species) or limit the records to
 a small number of species:
 
 ```python
 import os
 
-from ebird.api import (
-    get_notable_observations, 
+from ebird.api.requests import (
+    get_notable_observations,
     get_nearby_notable,
-    get_species_observations, 
+    get_species_observations,
     get_nearby_species,
 )
 
@@ -175,14 +174,14 @@ 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 
+import os
 
-from ebird.api import get_nearest_species
+from ebird.api.requests 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. 
+# Tennessee Warbler.
 locations = get_nearest_species(api_key, 'tenwar', 42.48, -76.45)
 ```
 
@@ -192,13 +191,13 @@ Depending on what time of year you try this, you might have a long way to go.
 
 There are two functions for finding out what has been seen at a given location.
 First you can get the list of checklists for a given country, region or location
-using get_visits(). Each result returned has the unique identifier for the 
+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
+from ebird.api.requests import get_visits, get_checklist
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -223,7 +222,7 @@ on the location of a given hotspot.
 ```python
 import os
 
-from ebird.api import get_hotspots, get_nearby_hotspots, get_hotspot
+from ebird.api.requests import get_hotspots, get_nearby_hotspots, get_hotspot
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -242,15 +241,15 @@ details = get_hotspot(api_key, 'L2313391')
 
 ### Regions
 
-eBird divides the world into countries, subnational1 regions (states) or 
-subnational2 regions (counties). You can use get_regions() to get the 
-list of sub-regions for a given region. For the approximate area covered 
+eBird divides the world into countries, subnational1 regions (states) or
+subnational2 regions (counties). You can use get_regions() to get the
+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
+from ebird.api.requests import get_regions, get_adjacent_regions, get_region
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -274,14 +273,14 @@ bounds = get_region(api_key, 'US-NY')
 
 You can get details of all the species, subspecies, forms
 etc. in the taxonomy used by eBird. It's the easiest way
-of getting the codes for each species or subspecies, 
+of getting the codes for each species or subspecies,
 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
+from ebird.api.requests import get_taxonomy, get_taxonomy_forms, get_taxonomy_versions
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -307,14 +306,14 @@ versions = get_taxonomy_versions(api_key)
 You can also get some statistics from the eBird data. The most interesting
 is probably get_top_100() which returns the list of observers who have seen
 the most species or submitted the largest number of checklists. The list is
-just for a specific day so it is really only useful for "Big Days" when 
+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
+from ebird.api.requests import get_top_100, get_totals
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -334,7 +333,7 @@ have to keep passing them as arguments.
 ```python
 import os
 
-from ebird.api import Client
+from ebird.api.requests import Client
 
 api_key = os.environ["EBIRD_API_KEY"]
 locale = 'es'
@@ -349,20 +348,36 @@ The client supports all the API functions.
 
 ## Formats
 
-Most of the eBird API calls return JSON. Some of the calls such as getting 
-the hotspots for a region or getting the taxonomy also support CSV. Since 
-converting JSON to CSV is simple this library is opinionated in that it 
+Most of the eBird API calls return JSON. Some of the calls such as getting
+the hotspots for a region or getting the taxonomy also support CSV. Since
+converting JSON to CSV is simple this library is opinionated in that it
 only returns JSON.
 
 ## Compatibility
 
-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 
+ebird-api works with currently supported versions of Python, 3.10+. However,
+it is known to work with earlier versions, at least 3.5 - 3.8, without any
 problems.
 
+## Troubleshooting
+
+Just occasionally (rarely in fact), the connection to eBird will freeze. The
+client will raise an error but if you use the API functions directly then your
+program will sit there forever. To fix this set a default timeout all connections
+using:
+
+```python
+import socket
+
+socket.setdefaulttimeout(30)
+```
+
+Thirty seconds is a reasonable figure, however you might change it if your
+internet connection is slow or the eBird servers are busy.
+
 ## Links
 
-Documentation for the eBird API: https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#intro 
+Documentation for the eBird API: https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#intro
 though it could do with a little love and attention.
 
 Available translations for species names: http://help.ebird.org/customer/portal/articles/1596582

{ebird_api-3.4.1 → ebird_api-4.0.0}/README.md

@@ -1,11 +1,10 @@
-[![Build Status](https://travis-ci.org/ProjectBabbler/ebird-api.svg?branch=master)](https://travis-ci.org/ProjectBabbler/ebird-api)
 [![PyPI version](https://badge.fury.io/py/ebird-api.svg)](https://badge.fury.io/py/ebird-api)
 [![Supported Python Versions](https://img.shields.io/pypi/pyversions/ebird-api.svg)](https://img.shields.io/pypi/pyversions/ebird-api)
 
 # eBird API
 
-eBird API provides a set of wrapper functions for accessing the end-points
-in the eBird API 2.0.
+eBird API Requests provides a set of wrapper functions for accessing the
+end-points in the eBird API 2.0.
 
 ## Install
 
@@ -16,23 +15,23 @@ pip install ebird-api
 ## Usage
 
 Each of the functions map to a specific end-point in the API - with one or
-two exceptions where API calls are essentially identical. The functions can 
-be grouped into five activities: fetching observations, getting information 
-on hotspots, getting information on regions, getting lists of species and 
+two exceptions where API calls are essentially identical. The functions can
+be grouped into five activities: fetching observations, getting information
+on hotspots, getting information on regions, getting lists of species and
 getting statistics.
 
-All functions support arguments (with sensible defaults) for all the query 
-parameters supported by the eBird API. Check the docstring for each function 
-for more details. There you will also find a link to the documentation for 
+All functions support arguments (with sensible defaults) for all the query
+parameters supported by the eBird API. Check the docstring for each function
+for more details. There you will also find a link to the documentation for
 each end-point.
 
-To use the API you will need to register for an API key. All you need to do is 
-fill out this [form](https://ebird.org/api/keygen) and the API key is generated 
+To use the API you will need to register for an API key. All you need to do is
+fill out this [form](https://ebird.org/api/keygen) and the API key is generated
 automatically.
 
-NOTE: Use the API with some restraint. Data costs money so don't go downloading 
-all the checklists for the world or other excessive behaviour or your account will 
-get banned. If you have a project in mind get in touch with eBird and tell them 
+NOTE: Use the API with some restraint. Data costs money so don't go downloading
+all the checklists for the world or other excessive behaviour or your account will
+get banned. If you have a project in mind get in touch with eBird and tell them
 what you want to do - they will be interested to hear it.
 
 ### Observations
@@ -40,12 +39,12 @@ what you want to do - they will be interested to hear it.
 ```python
 import os
 
-from ebird.api import get_observations
+from ebird.api.requests 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.
 this_week = get_observations(api_key, 'L227544', back=7)
 
@@ -59,14 +58,14 @@ state_records = get_observations(api_key, 'US-NY')
 national_records = get_observations(api_key, 'US')
 ```
 
-Any where you pass in single location or region you can also pass in a 
-list or a comma-separated string. You can specify up to 10 locations or 
+Any where you pass in single location or region you can also pass in a
+list or a comma-separated string. You can specify up to 10 locations or
 regions:
 
 ```python
 import os
 
-from ebird.api import get_observations
+from ebird.api.requests import get_observations
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -81,14 +80,14 @@ 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 
+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
+from ebird.api.requests import get_observations
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -96,34 +95,34 @@ records = get_observations(api_key, 'CA-QC', locale='fr')
 ```
 
 In addition to getting all the observations for a given location or in
-an area you can also get the latest observation of each species in a 
+an area you can also get the latest observation of each species in a
 geographical area - useful for finding the nearest place to see a given
 species:
 
 ```python
 import os
 
-from ebird.api import get_nearby_observations
+from ebird.api.requests 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 
+# 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)
 ```
 
-The calls to get_observations() and get_nearby_observation() return all the 
-available records. You can limit the set of records returned to only include 
-notable ones (locally or nationally rare species) or limit the records to 
+The calls to get_observations() and get_nearby_observation() return all the
+available records. You can limit the set of records returned to only include
+notable ones (locally or nationally rare species) or limit the records to
 a small number of species:
 
 ```python
 import os
 
-from ebird.api import (
-    get_notable_observations, 
+from ebird.api.requests import (
+    get_notable_observations,
     get_nearby_notable,
-    get_species_observations, 
+    get_species_observations,
     get_nearby_species,
 )
 
@@ -145,14 +144,14 @@ 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 
+import os
 
-from ebird.api import get_nearest_species
+from ebird.api.requests 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. 
+# Tennessee Warbler.
 locations = get_nearest_species(api_key, 'tenwar', 42.48, -76.45)
 ```
 
@@ -162,13 +161,13 @@ Depending on what time of year you try this, you might have a long way to go.
 
 There are two functions for finding out what has been seen at a given location.
 First you can get the list of checklists for a given country, region or location
-using get_visits(). Each result returned has the unique identifier for the 
+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
+from ebird.api.requests import get_visits, get_checklist
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -193,7 +192,7 @@ on the location of a given hotspot.
 ```python
 import os
 
-from ebird.api import get_hotspots, get_nearby_hotspots, get_hotspot
+from ebird.api.requests import get_hotspots, get_nearby_hotspots, get_hotspot
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -212,15 +211,15 @@ details = get_hotspot(api_key, 'L2313391')
 
 ### Regions
 
-eBird divides the world into countries, subnational1 regions (states) or 
-subnational2 regions (counties). You can use get_regions() to get the 
-list of sub-regions for a given region. For the approximate area covered 
+eBird divides the world into countries, subnational1 regions (states) or
+subnational2 regions (counties). You can use get_regions() to get the
+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
+from ebird.api.requests import get_regions, get_adjacent_regions, get_region
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -244,14 +243,14 @@ bounds = get_region(api_key, 'US-NY')
 
 You can get details of all the species, subspecies, forms
 etc. in the taxonomy used by eBird. It's the easiest way
-of getting the codes for each species or subspecies, 
+of getting the codes for each species or subspecies,
 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
+from ebird.api.requests import get_taxonomy, get_taxonomy_forms, get_taxonomy_versions
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -277,14 +276,14 @@ versions = get_taxonomy_versions(api_key)
 You can also get some statistics from the eBird data. The most interesting
 is probably get_top_100() which returns the list of observers who have seen
 the most species or submitted the largest number of checklists. The list is
-just for a specific day so it is really only useful for "Big Days" when 
+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
+from ebird.api.requests import get_top_100, get_totals
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -304,7 +303,7 @@ have to keep passing them as arguments.
 ```python
 import os
 
-from ebird.api import Client
+from ebird.api.requests import Client
 
 api_key = os.environ["EBIRD_API_KEY"]
 locale = 'es'
@@ -319,20 +318,36 @@ The client supports all the API functions.
 
 ## Formats
 
-Most of the eBird API calls return JSON. Some of the calls such as getting 
-the hotspots for a region or getting the taxonomy also support CSV. Since 
-converting JSON to CSV is simple this library is opinionated in that it 
+Most of the eBird API calls return JSON. Some of the calls such as getting
+the hotspots for a region or getting the taxonomy also support CSV. Since
+converting JSON to CSV is simple this library is opinionated in that it
 only returns JSON.
 
 ## Compatibility
 
-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 
+ebird-api works with currently supported versions of Python, 3.10+. However,
+it is known to work with earlier versions, at least 3.5 - 3.8, without any
 problems.
 
+## Troubleshooting
+
+Just occasionally (rarely in fact), the connection to eBird will freeze. The
+client will raise an error but if you use the API functions directly then your
+program will sit there forever. To fix this set a default timeout all connections
+using:
+
+```python
+import socket
+
+socket.setdefaulttimeout(30)
+```
+
+Thirty seconds is a reasonable figure, however you might change it if your
+internet connection is slow or the eBird servers are busy.
+
 ## Links
 
-Documentation for the eBird API: https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#intro 
+Documentation for the eBird API: https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#intro
 though it could do with a little love and attention.
 
 Available translations for species names: http://help.ebird.org/customer/portal/articles/1596582

{ebird_api-3.4.1 → ebird_api-4.0.0}/pyproject.toml

@@ -14,11 +14,10 @@ classifiers = [
     "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 :: 3.13",
     "Programming Language :: Python :: Implementation :: CPython",
     "Natural Language :: English",
     "Topic :: Utilities",
@@ -29,8 +28,8 @@ keywords = ["eBird", "API", "client"]
 license = {text = "MIT License"}
 name = "ebird-api"
 readme = "README.md"
-requires-python = ">= 3.8"
-version = "3.4.1"
+requires-python = ">= 3.10"
+version = "4.0.0"
 
 [project.urls]
 Repository = "https://github.com/ProjectBabbler/ebird-api.git"
@@ -38,7 +37,7 @@ Issues = "https://github.com/ProjectBabbler/ebird-api/issues"
 Changelog = "https://github.com/ProjectBabbler/ebird-api/blob/master/CHANGELOG.md"
 
 [tool.bumpversion]
-current_version = "3.4.1"
+current_version = "4.0.0"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 ignore_missing_version = false
@@ -52,7 +51,7 @@ message = "New version: {current_version} → {new_version}"
 commit_args = ""
 
 [[tool.bumpversion.files]]
-filename = "src/ebird/api/__init__.py"
+filename = "src/ebird/api/requests/__init__.py"
 search = '__version__ = "{current_version}"'
 replace = '__version__ = "{new_version}"'
 
@@ -98,7 +97,7 @@ legacy_tox_ini = """
 requires =
     tox>=4.2
     tox-uv>=1.11.3
-envlist = py38, py39, py310, py311, py312
+envlist = py310, py311, py312, py313
 
 [testenv]
 commands = pytest

ebird_api-4.0.0/src/ebird/api/requests/__init__.py

@@ -0,0 +1,39 @@
+# flake8: noqa
+
+"""A set of wrapper functions for accessing the eBird API."""
+
+__version__ = "4.0.0"
+
+from ebird.api.requests.checklists import get_checklist, get_visits
+from ebird.api.requests.client import Client
+from ebird.api.requests.constants import LOCALES
+from ebird.api.requests.hotspots import (
+    get_hotspot,
+    get_hotspots,
+    get_location,
+    get_nearby_hotspots,
+)
+from ebird.api.requests.observations import (
+    get_historic_observations,
+    get_nearby_notable,
+    get_nearby_observations,
+    get_nearby_species,
+    get_nearest_species,
+    get_notable_observations,
+    get_observations,
+    get_species_observations,
+)
+from ebird.api.requests.regions import (
+    get_adjacent_regions,
+    get_region,
+    get_regions,
+)
+from ebird.api.requests.species import get_species_list
+from ebird.api.requests.statistics import get_top_100, get_totals
+from ebird.api.requests.taxonomy import (
+    get_taxonomy,
+    get_taxonomy_forms,
+    get_taxonomy_groups,
+    get_taxonomy_locales,
+    get_taxonomy_versions,
+)

{ebird_api-3.4.1/src/ebird/api → ebird_api-4.0.0/src/ebird/api/requests}/checklists.py

@@ -1,7 +1,7 @@
 """Functions for fetching checklists and information about visits."""
 
-from ebird.api.utils import call
-from ebird.api.validation import (
+from ebird.api.requests.utils import call
+from ebird.api.requests.validation import (
     clean_area,
     clean_code,
     clean_date,

{ebird_api-3.4.1/src/ebird/api → ebird_api-4.0.0/src/ebird/api/requests}/client.py

@@ -2,7 +2,9 @@
 
 """Classes for simplifying calls to the eBird API."""
 
-from ebird.api import (
+import socket
+
+from ebird.api.requests import (
     checklists,
     constants,
     hotspots,
@@ -11,7 +13,7 @@ from ebird.api import (
     statistics,
     taxonomy,
 )
-from ebird.api.validation import clean_locale
+from ebird.api.requests.validation import clean_locale
 
 
 class Client:
@@ -41,6 +43,7 @@ class Client:
         self.hotspot = False
         self.provisional = True
         self.sort = "date"
+        socket.setdefaulttimeout(constants.DEFAULT_TIMEOUT)
 
     def get_observations(self, area):
         """Get recent observations (up to 30 days ago) for a region or location.

{ebird_api-3.4.1/src/ebird/api → ebird_api-4.0.0/src/ebird/api/requests}/constants.py

@@ -101,3 +101,8 @@ SPECIES_SORT = ["date", "species"]
 REGION_TYPES = ["country", "subnational1", "subnational2"]
 
 TOP_100_RANK = ["spp", "cl"]
+
+# Just occasionally the connection to eBird freezes. The timeout
+# will raise an error which is preferable to the sitting there
+# waiting for something to happen, when it will not.
+DEFAULT_TIMEOUT = 30

{ebird_api-3.4.1/src/ebird/api → ebird_api-4.0.0/src/ebird/api/requests}/hotspots.py

@@ -2,8 +2,8 @@
 
 from urllib.error import HTTPError
 
-from ebird.api.utils import call
-from ebird.api.validation import (
+from ebird.api.requests.utils import call
+from ebird.api.requests.validation import (
     clean_back,
     clean_dist,
     clean_lat,

{ebird_api-3.4.1/src/ebird/api → ebird_api-4.0.0/src/ebird/api/requests}/observations.py

@@ -2,8 +2,8 @@
 
 """Functions for fetching information about what species have been seen."""
 
-from ebird.api.utils import call
-from ebird.api.validation import (
+from ebird.api.requests.utils import call
+from ebird.api.requests.validation import (
     clean_areas,
     clean_back,
     clean_categories,

{ebird_api-3.4.1/src/ebird/api → ebird_api-4.0.0/src/ebird/api/requests}/regions.py

@@ -1,7 +1,7 @@
 """Functions for fetching information about regions."""
 
-from ebird.api.utils import call
-from ebird.api.validation import clean_region, clean_region_type
+from ebird.api.requests.utils import call
+from ebird.api.requests.validation import clean_region, clean_region_type
 
 REGION_LIST_URL = "https://api.ebird.org/v2/ref/region/list/%s/%s"
 ADJACENT_REGIONS_URL = "https://api.ebird.org/v2/ref/adjacent/%s"

{ebird_api-3.4.1/src/ebird/api → ebird_api-4.0.0/src/ebird/api/requests}/species.py

@@ -1,7 +1,7 @@
 """Functions for fetching information about species."""
 
-from ebird.api.utils import call
-from ebird.api.validation import clean_area
+from ebird.api.requests.utils import call
+from ebird.api.requests.validation import clean_area
 
 SPECIES_LIST_URL = "https://api.ebird.org/v2/product/spplist/%s"
 

{ebird_api-3.4.1/src/ebird/api → ebird_api-4.0.0/src/ebird/api/requests}/statistics.py

@@ -1,7 +1,7 @@
 """Functions for fetching basic statistics about observers and observations."""
 
-from ebird.api.utils import call
-from ebird.api.validation import (
+from ebird.api.requests.utils import call
+from ebird.api.requests.validation import (
     clean_area,
     clean_date,
     clean_max_observers,

{ebird_api-3.4.1/src/ebird/api → ebird_api-4.0.0/src/ebird/api/requests}/taxonomy.py

@@ -1,7 +1,7 @@
 """Functions for fetching information about the taxonomy used by eBird."""
 
-from ebird.api.utils import call
-from ebird.api.validation import (
+from ebird.api.requests.utils import call
+from ebird.api.requests.validation import (
     clean_categories,
     clean_codes,
     clean_locale,

{ebird_api-3.4.1/src/ebird/api → ebird_api-4.0.0/src/ebird/api/requests}/utils.py

@@ -4,7 +4,7 @@ import json
 from urllib.parse import urlencode
 from urllib.request import Request, urlopen
 
-from ebird.api import constants
+from ebird.api.requests import constants
 
 _parameter_defaults = {
     "back": constants.DEFAULT_BACK,

{ebird_api-3.4.1/src/ebird/api → ebird_api-4.0.0/src/ebird/api/requests}/validation.py

@@ -6,7 +6,7 @@ import re
 from datetime import date, datetime
 from enum import Enum
 
-from ebird.api import constants
+from ebird.api.requests import constants
 
 _locales = constants.LOCALES.values()
 _region_types = ", ".join(constants.REGION_TYPES)

{ebird_api-3.4.1 → ebird_api-4.0.0/src/ebird_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: ebird-api
-Version: 3.4.1
+Version: 4.0.0
 Summary: Wrapper for accessing the eBird API
 Author-email: Project Babbler <projectbabbler@gmail.com>
 License: MIT License
@@ -15,27 +15,26 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 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: Programming Language :: Python :: Implementation :: CPython
 Classifier: Natural Language :: English
 Classifier: Topic :: Utilities
 Classifier: Topic :: Internet
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
+Dynamic: license-file
 
-[![Build Status](https://travis-ci.org/ProjectBabbler/ebird-api.svg?branch=master)](https://travis-ci.org/ProjectBabbler/ebird-api)
 [![PyPI version](https://badge.fury.io/py/ebird-api.svg)](https://badge.fury.io/py/ebird-api)
 [![Supported Python Versions](https://img.shields.io/pypi/pyversions/ebird-api.svg)](https://img.shields.io/pypi/pyversions/ebird-api)
 
 # eBird API
 
-eBird API provides a set of wrapper functions for accessing the end-points
-in the eBird API 2.0.
+eBird API Requests provides a set of wrapper functions for accessing the
+end-points in the eBird API 2.0.
 
 ## Install
 
@@ -46,23 +45,23 @@ pip install ebird-api
 ## Usage
 
 Each of the functions map to a specific end-point in the API - with one or
-two exceptions where API calls are essentially identical. The functions can 
-be grouped into five activities: fetching observations, getting information 
-on hotspots, getting information on regions, getting lists of species and 
+two exceptions where API calls are essentially identical. The functions can
+be grouped into five activities: fetching observations, getting information
+on hotspots, getting information on regions, getting lists of species and
 getting statistics.
 
-All functions support arguments (with sensible defaults) for all the query 
-parameters supported by the eBird API. Check the docstring for each function 
-for more details. There you will also find a link to the documentation for 
+All functions support arguments (with sensible defaults) for all the query
+parameters supported by the eBird API. Check the docstring for each function
+for more details. There you will also find a link to the documentation for
 each end-point.
 
-To use the API you will need to register for an API key. All you need to do is 
-fill out this [form](https://ebird.org/api/keygen) and the API key is generated 
+To use the API you will need to register for an API key. All you need to do is
+fill out this [form](https://ebird.org/api/keygen) and the API key is generated
 automatically.
 
-NOTE: Use the API with some restraint. Data costs money so don't go downloading 
-all the checklists for the world or other excessive behaviour or your account will 
-get banned. If you have a project in mind get in touch with eBird and tell them 
+NOTE: Use the API with some restraint. Data costs money so don't go downloading
+all the checklists for the world or other excessive behaviour or your account will
+get banned. If you have a project in mind get in touch with eBird and tell them
 what you want to do - they will be interested to hear it.
 
 ### Observations
@@ -70,12 +69,12 @@ what you want to do - they will be interested to hear it.
 ```python
 import os
 
-from ebird.api import get_observations
+from ebird.api.requests 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.
 this_week = get_observations(api_key, 'L227544', back=7)
 
@@ -89,14 +88,14 @@ state_records = get_observations(api_key, 'US-NY')
 national_records = get_observations(api_key, 'US')
 ```
 
-Any where you pass in single location or region you can also pass in a 
-list or a comma-separated string. You can specify up to 10 locations or 
+Any where you pass in single location or region you can also pass in a
+list or a comma-separated string. You can specify up to 10 locations or
 regions:
 
 ```python
 import os
 
-from ebird.api import get_observations
+from ebird.api.requests import get_observations
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -111,14 +110,14 @@ 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 
+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
+from ebird.api.requests import get_observations
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -126,34 +125,34 @@ records = get_observations(api_key, 'CA-QC', locale='fr')
 ```
 
 In addition to getting all the observations for a given location or in
-an area you can also get the latest observation of each species in a 
+an area you can also get the latest observation of each species in a
 geographical area - useful for finding the nearest place to see a given
 species:
 
 ```python
 import os
 
-from ebird.api import get_nearby_observations
+from ebird.api.requests 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 
+# 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)
 ```
 
-The calls to get_observations() and get_nearby_observation() return all the 
-available records. You can limit the set of records returned to only include 
-notable ones (locally or nationally rare species) or limit the records to 
+The calls to get_observations() and get_nearby_observation() return all the
+available records. You can limit the set of records returned to only include
+notable ones (locally or nationally rare species) or limit the records to
 a small number of species:
 
 ```python
 import os
 
-from ebird.api import (
-    get_notable_observations, 
+from ebird.api.requests import (
+    get_notable_observations,
     get_nearby_notable,
-    get_species_observations, 
+    get_species_observations,
     get_nearby_species,
 )
 
@@ -175,14 +174,14 @@ 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 
+import os
 
-from ebird.api import get_nearest_species
+from ebird.api.requests 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. 
+# Tennessee Warbler.
 locations = get_nearest_species(api_key, 'tenwar', 42.48, -76.45)
 ```
 
@@ -192,13 +191,13 @@ Depending on what time of year you try this, you might have a long way to go.
 
 There are two functions for finding out what has been seen at a given location.
 First you can get the list of checklists for a given country, region or location
-using get_visits(). Each result returned has the unique identifier for the 
+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
+from ebird.api.requests import get_visits, get_checklist
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -223,7 +222,7 @@ on the location of a given hotspot.
 ```python
 import os
 
-from ebird.api import get_hotspots, get_nearby_hotspots, get_hotspot
+from ebird.api.requests import get_hotspots, get_nearby_hotspots, get_hotspot
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -242,15 +241,15 @@ details = get_hotspot(api_key, 'L2313391')
 
 ### Regions
 
-eBird divides the world into countries, subnational1 regions (states) or 
-subnational2 regions (counties). You can use get_regions() to get the 
-list of sub-regions for a given region. For the approximate area covered 
+eBird divides the world into countries, subnational1 regions (states) or
+subnational2 regions (counties). You can use get_regions() to get the
+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
+from ebird.api.requests import get_regions, get_adjacent_regions, get_region
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -274,14 +273,14 @@ bounds = get_region(api_key, 'US-NY')
 
 You can get details of all the species, subspecies, forms
 etc. in the taxonomy used by eBird. It's the easiest way
-of getting the codes for each species or subspecies, 
+of getting the codes for each species or subspecies,
 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
+from ebird.api.requests import get_taxonomy, get_taxonomy_forms, get_taxonomy_versions
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -307,14 +306,14 @@ versions = get_taxonomy_versions(api_key)
 You can also get some statistics from the eBird data. The most interesting
 is probably get_top_100() which returns the list of observers who have seen
 the most species or submitted the largest number of checklists. The list is
-just for a specific day so it is really only useful for "Big Days" when 
+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
+from ebird.api.requests import get_top_100, get_totals
 
 api_key = os.environ["EBIRD_API_KEY"]
 
@@ -334,7 +333,7 @@ have to keep passing them as arguments.
 ```python
 import os
 
-from ebird.api import Client
+from ebird.api.requests import Client
 
 api_key = os.environ["EBIRD_API_KEY"]
 locale = 'es'
@@ -349,20 +348,36 @@ The client supports all the API functions.
 
 ## Formats
 
-Most of the eBird API calls return JSON. Some of the calls such as getting 
-the hotspots for a region or getting the taxonomy also support CSV. Since 
-converting JSON to CSV is simple this library is opinionated in that it 
+Most of the eBird API calls return JSON. Some of the calls such as getting
+the hotspots for a region or getting the taxonomy also support CSV. Since
+converting JSON to CSV is simple this library is opinionated in that it
 only returns JSON.
 
 ## Compatibility
 
-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 
+ebird-api works with currently supported versions of Python, 3.10+. However,
+it is known to work with earlier versions, at least 3.5 - 3.8, without any
 problems.
 
+## Troubleshooting
+
+Just occasionally (rarely in fact), the connection to eBird will freeze. The
+client will raise an error but if you use the API functions directly then your
+program will sit there forever. To fix this set a default timeout all connections
+using:
+
+```python
+import socket
+
+socket.setdefaulttimeout(30)
+```
+
+Thirty seconds is a reasonable figure, however you might change it if your
+internet connection is slow or the eBird servers are busy.
+
 ## Links
 
-Documentation for the eBird API: https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#intro 
+Documentation for the eBird API: https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#intro
 though it could do with a little love and attention.
 
 Available translations for species names: http://help.ebird.org/customer/portal/articles/1596582

ebird_api-4.0.0/src/ebird_api.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+CHANGELOG.md
+LICENSE.txt
+README.md
+pyproject.toml
+setup.py
+src/ebird/api/requests/__init__.py
+src/ebird/api/requests/checklists.py
+src/ebird/api/requests/client.py
+src/ebird/api/requests/constants.py
+src/ebird/api/requests/hotspots.py
+src/ebird/api/requests/observations.py
+src/ebird/api/requests/regions.py
+src/ebird/api/requests/species.py
+src/ebird/api/requests/statistics.py
+src/ebird/api/requests/taxonomy.py
+src/ebird/api/requests/utils.py
+src/ebird/api/requests/validation.py
+src/ebird_api.egg-info/PKG-INFO
+src/ebird_api.egg-info/SOURCES.txt
+src/ebird_api.egg-info/dependency_links.txt
+src/ebird_api.egg-info/top_level.txt

ebird_api-3.4.1/src/ebird/api/__init__.py

@@ -1,35 +0,0 @@
-# flake8: noqa
-
-"""A set of wrapper functions for accessing the eBird API."""
-
-__version__ = "3.4.1"
-
-from ebird.api.checklists import get_checklist, get_visits
-from ebird.api.client import Client
-from ebird.api.constants import LOCALES
-from ebird.api.hotspots import (
-    get_hotspot,
-    get_hotspots,
-    get_location,
-    get_nearby_hotspots,
-)
-from ebird.api.observations import (
-    get_historic_observations,
-    get_nearby_notable,
-    get_nearby_observations,
-    get_nearby_species,
-    get_nearest_species,
-    get_notable_observations,
-    get_observations,
-    get_species_observations,
-)
-from ebird.api.regions import get_adjacent_regions, get_region, get_regions
-from ebird.api.species import get_species_list
-from ebird.api.statistics import get_top_100, get_totals
-from ebird.api.taxonomy import (
-    get_taxonomy,
-    get_taxonomy_forms,
-    get_taxonomy_groups,
-    get_taxonomy_locales,
-    get_taxonomy_versions,
-)

ebird_api-3.4.1/src/ebird_api.egg-info/SOURCES.txt

@@ -1,21 +0,0 @@
-CHANGELOG.md
-LICENSE.txt
-README.md
-pyproject.toml
-setup.py
-src/ebird/api/__init__.py
-src/ebird/api/checklists.py
-src/ebird/api/client.py
-src/ebird/api/constants.py
-src/ebird/api/hotspots.py
-src/ebird/api/observations.py
-src/ebird/api/regions.py
-src/ebird/api/species.py
-src/ebird/api/statistics.py
-src/ebird/api/taxonomy.py
-src/ebird/api/utils.py
-src/ebird/api/validation.py
-src/ebird_api.egg-info/PKG-INFO
-src/ebird_api.egg-info/SOURCES.txt
-src/ebird_api.egg-info/dependency_links.txt
-src/ebird_api.egg-info/top_level.txt