removes the obsolete Catalog API and improves README

dpfens · dpfens · commit 9344cd4b3cbb · 2024-03-10T21:13:06.000-04:00
diff --git a/README.md b/README.md
@@ -2,167 +2,54 @@
 A Python 2/3 wrapper for the World Bank API
 See World Bank [Developer Information](https://datahelpdesk.worldbank.org/knowledgebase/topics/125589-developer-information) to get information on the raw API
 
-## Classes
-Classes are used to store the data returned by the API and the `classmethods` and Instance Methods are used to fetch data from the API
-
-- [Catalog](#catalog)
-- [City](#city)
-- [Country](#country)
-- [CountryIndicator](#countryindicator)
-- [IncomeLevel](#incomelevel)
-- [Indicator](#indicator)
-- [LendingType](#lendingtype)
-- [Region](#region)
-    - [AdminRegion](#adminregion)
-- [Source](#source)
-- [Topic](#topic)
-
-
-### Catalog
-The Data Catalog API provides programmatic access to the list of datasets in the [World Bank’s Open Data Catalog](https://data.worldbank.org/data-catalog/) with associated metadata.  Each metatype returned is added to the instance as an attribute.
-
-#### Instance Attributes
-- id
-
-See [World Bank Catalog API](https://datahelpdesk.worldbank.org/knowledgebase/articles/902049-data-catalog-api) for more details
-
-### City
-A city in a [country](#country). A `country`'s `capital` is a `City` instance
-
-#### Instance Attributes
-- name
-- latitude
-- longitude
-
-#### Instance Methods
-- get(page=1, per_page=50]
-
-### Country
-A country existing in the World Bank database
-
-#### Instance Attributes
-- id
-- name
-- iso_code
-- region - a [Region](#region) instance
-- admin_region - an [AdminRegion](#adminregion) instance
-- income_level - an [IncomeLevel](#incomelevel) instance
-- lending_type - a [LendingType](#lendingtype) instance
-- capital - A [City](#city) instance
-
-#### Instance Methods
-- get(iso_code=None, page=1, per_page=50]
-    - If an iso_code is not provided, returns a list of all [Countries](#country).  If an iso_code is provided, returns a [Country](#country) instance of the given iso_code.
-- by_income_level(income_level]
-    - Returns [Countries](#country) that all have a given [IncomeLevel](#incomelevel)
-- by_lending_type(lending_type]
-    - Returns [Countries](#country) that all have a given [LendingType](#lendingtype)
-
-See the [World Bank Country API](https://datahelpdesk.worldbank.org/knowledgebase/articles/898590-api-country-queries) for more details
-
-### CountryIndicator
-A measure of an [Indicator](#indicator) for a given country for a given year
-
-#### Instance Attributes
-- Indicator - an instance of an [Indicator](#indicator)
-- country
-    - id
-    - name
-- year - year when the measure of the indicator occurred
-- value - floating point number
-- decimal - a measure of precision of the returned value
-
-#### Instance Methods
-- get(indicator, country='all', page=1, per_page=50, start=None, end=None]
-    - Returns instances of `CountryIndicator` for a given [Indicator](#indicator).  If a `start` year and `end` year are provided, returns `CountryIndicators` where `start` >= year <= `end`.
-    - If a country is provided, only returns `CountryIndicators` for the given country. If a country is not provided, returns `CountryIndicators` for the [Indicator](#indicator) for all countries.
-
-See the [World Bank Indicator API](See https://datahelpdesk.worldbank.org/knowledgebase/articles/898599-api-indicator-queries) for more details
-
-
-### IncomeLevel
-Income levels show the income category of a particular country as identified by the World Bank.  For more information see the [World Bank Country and Lending Groups](https://datahelpdesk.worldbank.org/knowledgebase/articles/906519-world-bank-country-and-lending-groups) page.
-
-#### Instance Attributes
-- id
-- name
 
-#### Instance Methods
-- get(page=1, per_page=50]
-    - Returns a list of all [IncomeLevels](#incomelevel)
+## Quickstart
+```python
+from worldbank import api as wb
+
+summary, indicators = wb.Indicator.get()
+summary, country_indicators = wb.CountryIndicator.get(indicators[0])
+summary, countries = wb.Country.get()
+summary, lending_types = wb.LendingType.get()
+summary, topics = wb.Topic.get()
+summary, sources = wb.Source.get()
+summary, income_levels = wb.IncomeLevel.get()
+summary, indicators = wb.Indicator.get()
+summary, countries = wb.Country.by_income_level(income_level=income_levels[0])
+summary, country = wb.Country.by_lending_type(lending_types[0])
+summary, indicators = wb.Indicator.by_source(sources[0])
+summary, indicators = wb.Indicator.by_topic(topics[0])
+summary, country_indicators = wb.CountryIndicator.get(indicators[0])
+```
 
-See the [World Bank Income Level API](https://datahelpdesk.worldbank.org/knowledgebase/articles/898596-api-income-level-queries) for more details.
-
-### Indicator
-
-#### Instance Attributes
-- id
-- name
-- source - A [Source](#source) instance
-- topics - A list of [Topics](#topic)
-- source_note - a description of the indicator by the `source_organization`
-- source_organization - The name of the organization providing the data for the indicator
-
-#### Instance Methods
-- get(indicator_id=None, page=1, per_page=50]
-    - If a indicator_id is provided, returns a single [Indicator](#indicator).  If an indicator_id is not provided, then all [Indicators](#indicator) will be returned based on the `page` and `per_page` parameter
-- by_source(source, page=1, per_page=50]
-    - Returns [Indicators](#indicator) that all come from the [Source](#source)
-- by_topic(topic]
-    - Returns [Indicators](#indicator) that all have a given [Topic](#topic)
-
-See the [World Bank Indicator API](https://datahelpdesk.worldbank.org/knowledgebase/articles/898599-api-indicator-queries) for more details.
-
-### LendingType
-The World Bank classified countries according to the type of lending they are eligible for through the World Bank.  For more information see the [World Bank Country and Lending Groups](https://datahelpdesk.worldbank.org/knowledgebase/articles/906519-world-bank-country-and-lending-groups) page.
-
-#### Instance Attributes
-- id
-- name
-
-#### Instance Methods
-- get(page=1, per_page=50]
-    - Returns a list of all [LendingTypes](#lendingtypes)
-
-See the [World Bank Lending Type API](https://datahelpdesk.worldbank.org/knowledgebase/articles/898608-api-lending-type-queries) for more details
-
-### Region
-
-#### Instance Attributes
-- id
-- name
-
-#### AdminRegion
-
-#### Instance Attributes
-- id
-- name
-
-### Source
-An organization that provides data as [CountryIndicators](#countryindicator) for a given number of [Indicators](#indicator)
-
-#### Instance Attributes
-- id
-- name
-- description
-- url
-
-#### Instance Methods
-- get(page=1, per_page=50]
-    - Returns a list of all [Sources](#source)
-
-See the [World Bank Source API](https://datahelpdesk.worldbank.org/knowledgebase/articles/898587-api-catalog-source-queries) for more details
-
-### Topic
-A high-level category that all [Indicators](#indicator) are mapped to
-
-#### Instance Attributes
-- id
-- name
-- note
-
-#### Instance Methods
-- get(page=1, per_page=50]
-    - Returns a list of all [Topics](#topic)
+Classes are used to store the data returned by the API and the `classmethods` and Instance Methods are used to fetch data from the API
 
-See the [World Bank Topic API](https://datahelpdesk.worldbank.org/knowledgebase/articles/898611-api-topic-queries) for more details
+* Catalog
+* City
+* Country
+* CountryIndicator
+* IncomeLevel
+* Indicator
+* LendingType
+* Region
+  * AdminRegion
+* Source
+* Topic
+
+## Pagination
+The API wrapper allows pagination and adjusting page sizes of data using the `page` number and `per_page` `number:
+```python
+from worldbank import api as wb
+
+instances = []
+current_page = 1
+total_pages = float('inf')
+total_instances = float('inf')
+per_page = 500
+while current_page <= total_pages:
+    summary, page_instances = Indicator.get(page=current_page, per_page=per_page)
+    total_pages = summary['pages']
+    total_instances = summary['total']
+    current_page += 1
+    instances += page_instances
+```
diff --git a/README.rst b/README.rst
diff --git a/setup.py b/setup.py
@@ -17,7 +17,7 @@
     # Versions should comply with PEP440.  For a discussion on single-sourcing
     # the version across setup.py and the project code, see
     # https://packaging.python.org/en/latest/single_source_version.html
-    version='0.2',
+    version='1.1',
 
     description='A Python 2/3 API wrapper for World Bank',
     long_description=long_description,
diff --git a/worldbank/api.py b/worldbank/api.py
@@ -675,78 +675,6 @@ def get(cls, **kwargs):
         return summary, instances
 
 
-class Catalog(object):
-    """
-    A Dataset in the World Bank Open Data Datalog
-
-    Attributes:
-        id (str):
-        metatypes (list):
-
-    See https://datahelpdesk.worldbank.org/knowledgebase/articles/902049-data-catalog-api
-    """
-
-    def __init__(self, id, metatypes):
-        self.id = id
-        self.metatypes = metatypes
-
-    def __str__(self):
-        return self.id
-
-    def __repr__(self):
-        return '<%s %s id=%s>' % (self.__class__.__name__, id(self), self.id)
-
-    @classmethod
-    def from_api(cls, data):
-        """
-        Returns a class instance from API data
-        """
-        catalog_id = data['id']
-        metatypes = data['metatype']
-        return cls(catalog_id, metatypes)
-
-    @classmethod
-    def get(cls, catalog=None, field=[], **kwargs):
-        """
-        Arguments:
-            catalog (str, optional): id of the desired Catalog
-            field (list|tuple|set):  desired fields
-        Keyword Arguments:
-            page (int, optional):  The page number to get, defaults to 1.
-            per_page (int, optional):  The number of items to fetch in each page, defaults to 50.
-
-        Returns
-            list: instances matching the query
-        """
-        field = ';'.join(field)
-        url = '%s/datacatalog/' % domain
-        if catalog:
-            url = '%s/%s' % (url, catalog.id)
-        if field:
-            url = '%s/metatypes/%s' % (url, field)
-        data = _request(url, parameters=kwargs)
-        instances = [cls.from_api(item) for item in data['datacatalog']]
-        return instances
-
-    @classmethod
-    def search(cls, query, **kwargs):
-        """
-        Arguments:
-            query (str):  search query
-
-        Keyword Arguments:
-            page (int, optional):  The page number to get, defaults to 1.
-            per_page (int, optional):  The number of items to fetch in each page, defaults to 50.
-
-        Returns
-            list: instances matching the query
-        """
-        url = '%s/v2/datacatalog/search/%s' % (domain, query)
-        data = _request(url, parameters=kwargs)
-        instances = [cls.from_api(item) for item in data['datacatalog']]
-        return instances
-
-
 if __name__ == '__main__':
     summary, indicators = Indicator.get()
     summary, country_indicators = CountryIndicator.get(indicators[0])
@@ -760,5 +688,4 @@ def search(cls, query, **kwargs):
     summary, country = Country.by_lending_type(lending_types[0])
     summary, indicators = Indicator.by_source(sources[0])
     summary, indicators = Indicator.by_topic(topics[0])
-    summary, countryindicators = CountryIndicator.get(indicators[0])
-    catalog = Catalog.get()
+    summary, countryindicators = CountryIndicator.get(indicators[0])
