Merge pull request #102 from ipums/dev-0.6.0

v0.6.0

.github/workflows/main.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
 
     steps:
       - uses: actions/checkout@v4

.gitignore

@@ -5,13 +5,15 @@ __pycache__
 .venv
 .pytest_cache
 dist
+.python-version
 
 # Editor cruft
 .vscode
 .*.swp
 
 # Secrets
 .env.test
+.env
 
 # Docs
 docs/_build/
@@ -25,3 +27,6 @@ coverage.xml
 
 # pycharm ide settings
 .idea/
+
+# Ignore .DS_Store files
+.DS_Store

docs/source/change-log.rst

@@ -11,6 +11,32 @@ This project adheres to `Semantic Versioning`_.
 .. _Semantic Versioning: http://semver.org/
 
 
+0.6.0
+-----
+
+* New Features
+
+  * Support for IPUMS NHGIS extract API, including
+
+    * :py:class:`~ipumspy.api.extract.AggregateDataExtract` class has been added to support IPUMS NHGIS extracts
+    * :py:class:`~ipumspy.api.extract.Dataset`, :py:class:`~ipumspy.api.extract.TimeSeriesTable`, and 
+      :py:class:`~ipumspy.api.extract.Shapefile` classes have been added for use when constructing IPUMS NHGIS extract requests.
+    * Support for downloading IPUMS NHGIS supplemental datasets via API
+
+  * Support for IPUMS NHGIS metadata API, including
+
+    * :py:meth:`~ipumspy.api.IpumsApiClient.get_metadata()` method to request IPUMS NHGIS metadata from the IPUMS API
+    * :py:class:`~ipumspy.api.metadata.DatasetMetadata`, :py:class:`~ipumspy.api.metadata.TimeSeriesTableMetadata`, and :py:class:`~ipumspy.api.metadata.DataTableMetadata` classes to request and store metadata for different types of IPUMS NHGIS data
+    * :py:meth:`~ipumspy.api.IpumsApiClient.get_metadata_catalog()` generator to retrieve an inventory for a given type of metadata resource.
+
+  * Added :py:class:`~ipumspy.api.exceptions.IpumsApiRateLimitException` for requests that exceed the IPUMS API rate limit.
+
+* Bug Fixes
+
+  * Fixed bug in ``initial_wait_time`` argument that prevented the use of ``submit-and-download`` command via the command line interface
+
+* The minimum supported Python version is now 3.9
+
 0.5.1
 -----
 2024-07-01

docs/source/cli.rst

@@ -7,7 +7,7 @@
 Command Line Interface
 ======================
 
-``ipumspy`` allows you to interact with the IPUMS API via the command line. If you
+ipumspy allows you to interact with the IPUMS API via the command line. If you
 have :doc:`installed <getting_started>` with ``pip``, then you should have an ``ipums``
 command available on the command line.
 
@@ -17,14 +17,13 @@ You can explore what commands are available by running the ``--help`` option:
 
     ipums --help
 
-In particular, suppose that you have specified an extract in an ``ipums.yml`` file
-as described in the :doc:`getting started guide <getting_started>`.
+In particular, suppose that you have specified an extract in an ``ipums.yaml`` file
+as described in the :ref:`IPUMS API introduction <using-yaml>`.
 
 .. code:: yaml
 
     description: Simple IPUMS extract
     collection: usa
-    api_version: 2
     samples:
       - us2012b
     variables:
@@ -35,7 +34,7 @@ Then you can submit, wait for, and download the extract in a single line:
 
 .. code:: bash
 
-    ipums submit-and-download -k <IPUMS_API_KEY> ipums.yml
+    ipums submit-and-download -k <IPUMS_API_KEY> ipums.yaml
 
 Much of the rest of the functionality of the library is also available on the command
 line, as this document describes.
@@ -51,14 +50,13 @@ Specifying Multiple Extracts
 ****************************
 
 You may create mutliple files specifying extracts. For instance, in addition to the
-``ipums.yml`` described above, you might also have a file called ``ipums_with_race.yml``
+``ipums.yaml`` described above, you might also have a file called ``ipums_with_race.yaml``
 which contains the following:
 
 .. code:: yaml
 
     description: Another extract
     collection: usa
-    api_version: 2
     samples:
       - us2012b
     variables:
@@ -70,25 +68,23 @@ Then the following command would submit and download this extract:
 
 .. code:: bash
 
-    ipums submit-and-download -k <IPUMS_API_KEY> ipums_with_race.yml
+    ipums submit-and-download -k <IPUMS_API_KEY> ipums_with_race.yaml
 
 Alternatively, the ``submit-and-download`` command also allows you to specify *multiple*
-extracts simultaneously. To do so, specify the ``ipums_multiple.yml`` file as follows:
+extracts simultaneously. To do so, specify the ``ipums_multiple.yaml`` file as follows:
 
 .. code:: yaml
 
     extracts:
     - description: Simple IPUMS extract
       collection: usa
-      api_version: 2
       samples:
         - us2012b
       variables:
         - AGE
         - SEX
     - description: Another extract
       collection: usa
-      api_version: 2
       samples:
         - us2012b
       variables:
@@ -102,7 +98,7 @@ command:
 
 .. code:: bash
 
-    ipums submit-and-download -k <IPUMS_API_KEY> ipums_multiple.yml
+    ipums submit-and-download -k <IPUMS_API_KEY> ipums_multiple.yaml
 
 Step-by-Step
 ************
@@ -114,7 +110,7 @@ functionlaity is available via the ``submit``, ``check``, and ``download`` comma
 
 .. code:: bash
 
-    ipums submit -k <IPUMS_API_KEY> ipums.yml
+    ipums submit -k <IPUMS_API_KEY> ipums.yaml
     # Your extract for collection usa has been successfully submitted with number 10
 
     ipums check -k <IPUMS_API_KEY> 10

docs/source/conf.py

@@ -123,7 +123,7 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 
-html_logo = "_static/ipums-h-n-rgb.png"
+html_logo = "_static/ipumspy-logo.png"
 html_favicon = "_static/ipums-favicon-152x152.png"
 html_theme_options = {
     "light_css_variables": {