feat: Version 1.0 (#69)

The 1.0 release of wbdata is not quite a full rewrite, but is pretty
much the next best thing. The architecture has been reworked, function
and argument names have been changed to be more consistent and clear,
and a few dependencies have been added for better and more reliable
functionality.

Features:

* Date arguments can now be strings, not just datetime.datetime objects.
  Strings can be in the year, month, or quarter formats used by the
  World Bank API or in any other format that can be handled by
  [dateparser][https://dateparser.readthedocs.io/en/latest/].
* Default cache behavior can be configured with environment variables,
  including the path, TTL, and max number of items to cache. See Cache
  Module documentation for details.
* Users can now create Client objects if they want to set cache behavior
  programmatically have multiple caches, or supply their own requests
  Session.
* Caching is now provided using the shelved_cache and cachetools
  libraries. Since a lot of annoying bugs seemed to come from wbdata's
  home-rolled cache implementation, this should be a good
  quality-of-life improvement for many people.
* Type annotations are available.

Breaking API Changes:

* Supported version of Python are now 3.8+.
* All of the metadata retrieval functions have been renamed to their
  plural forms to reflect the fact that they always return a sequence:
* The functions search_countries and search_indicators have been
  removed. Searching by name is now available using the query
  parameter of the get_countries and get_indicators functions.
* The parameter data_date has been renamed date.
* The parameter convert_dates has been renamed parse_dates.
* The parameter cache with a default value True has been replaced with
  a parameter skip_cache with a default value of False.

.github/workflows/publish.yaml

@@ -11,11 +11,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v1
+        uses: actions/checkout@v4
       - name: Setup Python
-        uses: actions/setup-python@v1.1.1
+        uses: actions/setup-python@v5
       - name: Install Poetry
-        uses: dschep/install-poetry-action@v1.2
+        uses: snok/install-poetry@v1.3.4
       - name: Publish
         env:
           POETRY_PYPI_TOKEN_PYPI: ${{ secrets.pypi_token }}

.github/workflows/tests.yaml

@@ -1,27 +1,60 @@
 name: Tests
 on:
   push:
+    branches:
+      - 'master'
   pull_request:
-  schedule:
-    - cron: "1 1 1 * *"
 jobs:
+  lint:
+    name: Lint
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.8"
+      - name: Install Ruff
+        run: pip install ruff
+      - name: Run Tests
+        run: ruff check wbdata
+  types:
+    name: Types
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.8"
+      - name: Install Poetry Action
+        uses: snok/install-poetry@v1.3.4
+      - name: Install Dependencies
+        run: poetry install --only main,types 
+      - name: Run mypy
+        run: poetry run mypy wbdata
   test:
     name: Tests
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ["3.6", "3.7", "3.8"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
         os: ["ubuntu-latest", "macos-latest", "windows-latest"]
+    defaults:
+      run:
+        shell: bash
     steps:
       - name: Checkout
-        uses: actions/checkout@v1
+        uses: actions/checkout@v4
       - name: Setup Python
-        uses: actions/setup-python@v1.1.1
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-      - name: Install Poetry
-        uses: dschep/install-poetry-action@v1.2
+      - name: Install Poetry Action
+        uses: snok/install-poetry@v1.3.4
       - name: Install Dependencies
-        run: poetry install -E pandas
+        run: poetry install --only main,tests -E pandas
       - name: Run Tests
         run: poetry run pytest

.gitignore

@@ -36,3 +36,5 @@ nosetests.xml
 
 # Docs
 docs/_build/
+
+.mypy_cache

.readthedocs.yml

@@ -1,8 +1,15 @@
 version: 2
 formats: all
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3"
 python:
   install:
     - method: pip
       path: .
       extra_requirements:
+        - pandas
         - docs
+mkdocs:
+  configuration: mkdocs.yml

.tool-versions

@@ -0,0 +1,2 @@
+poetry 1.7.1
+python 3.8.13

README.md

@@ -1,15 +1,15 @@
 # wbdata
 
-| Branch | Status                                                                                                                                                                                                     |
-|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| master | [![master branch status](https://github.com/OliverSherouse/wbdata/workflows/Tests/badge.svg?branch=master)](https://github.com/OliverSherouse/wbdata/actions?query=workflow%3A%22Tests%22+branch%3Amaster) |
-| dev    | [![dev branch status](https://github.com/OliverSherouse/wbdata/workflows/Tests/badge.svg?branch=dev)](https://github.com/OliverSherouse/wbdata/actions?query=workflow%3A%22Tests%22+branch%3Adev)          |
+[![Tests](https://github.com/OliverSherouse/wbdata/actions/workflows/tests.yaml/badge.svg?branch=master)](https://github.com/OliverSherouse/wbdata/actions/workflows/tests.yaml)
+[![Documentation Status](https://readthedocs.org/projects/wbdata/badge/?version=stable)](https://wbdata.readthedocs.io/en/stable/?badge=stable)
+[![PyPI version](https://badge.fury.io/py/wbdata.svg)](https://badge.fury.io/py/wbdata)
+[![Downloads](https://static.pepy.tech/badge/wbdata/month)](https://pepy.tech/project/wbdata)
 
 Wbdata is a simple python interface to find and request information from the
 World Bank's various databases, either as a dictionary containing full metadata
 or as a [pandas](http://pandas.pydata.org) DataFrame or series. Currently,
 wbdata wraps most of the [World Bank
 API](http://data.worldbank.org/developers/api-overview), and also adds some
-convenience functions for searching and retrieving information.
+convenience functionality for searching and retrieving information.
 
 Documentation is available at <http://wbdata.readthedocs.org/> .

docs/basic_functionality.md

@@ -0,0 +1,90 @@
+# Basic functionality
+
+The basic functionality for `wbdata` users is provided by a set of functions in
+the topic level package namespace.
+
+## Data Retrieval
+
+These are the functions for actually getting data values from the World Bank
+API.
+
+### Raw Data Retrieval
+
+::: wbdata.client.Client.get_data
+    options:
+        show_root_heading: true
+        show_root_full_path: false
+        heading_level: 4
+
+
+### Pandas Data Retrieval
+
+These functions require Pandas to be installed to work.
+
+::: wbdata.client.Client.get_series
+    options:
+        show_root_heading: true
+        show_root_full_path: false
+        heading_level: 4
+
+::: wbdata.client.Client.get_dataframe
+    options:
+        show_root_heading: true
+        show_root_full_path: false
+        heading_level: 4
+
+## Metadata Retrieval
+
+These functions, for the most part, are for finding the parameters you want to
+put into the data retrieval functions. These all return
+[SearchResult][wbdata.client.SearchResult], which are lists that pretty-print
+the table in an interactive environment, and which contain dictionary
+representations of the requested resource.
+
+### Searchable Metadata
+
+There are enough indicators and countries that it's annoying to look through 
+them, so the functions for retrieving information about them can be narrowed
+with additional facets and filtered with a search term or regular expression
+supplied to the `query` parameter.
+
+::: wbdata.client.Client.get_countries
+    options:
+        show_root_heading: true
+        show_root_full_path: false
+        heading_level: 4
+
+
+::: wbdata.client.Client.get_indicators
+    options:
+        show_root_heading: true
+        show_root_full_path: false
+        heading_level: 4
+
+### Indicator Facets
+
+::: wbdata.client.Client.get_sources
+    options:
+        show_root_heading: true
+        show_root_full_path: false
+        heading_level: 4
+
+::: wbdata.client.Client.get_topics
+    options:
+        show_root_heading: true
+        show_root_full_path: false
+        heading_level: 4
+
+### Country Facets
+
+::: wbdata.client.Client.get_incomelevels
+    options:
+        show_root_heading: true
+        show_root_full_path: false
+        heading_level: 4
+
+::: wbdata.client.Client.get_lendingtypes
+    options:
+        show_root_heading: true
+        show_root_full_path: false
+        heading_level: 4