agate-lookup 0.1.0

Build status PyPI downloads Version License Support Python versions

agate-lookup adds remote lookup tables to agate.

Important links:

Install

To install:

pip install agatelookup

For details on development or supported platforms see the agate documentation.

Usage

agate-lookup is an agate extension. To use it, first import it and patch its functionality into agate:

import agate
import agatelookup

agatelookup.patch()

Calling patch() attaches all the methods of Tablelookup to agate.Table.

After that, you simply use the TableLookup.lookup() method on your table, passing in the number of the columns to match on and the value you wish to lookup. For example, if you have this table:

company usps
Walmart AR
Exxon TX
Chevron CA

You could add the state name to the table by running:

joined = table.lookup('usps', 'state')

The resulting table would be:

company usps state
Walmart AR Arkansas
Exxon TX Texas
Chevron CA California

If your table has different keys from the lookup table, you can specify them using the table_keys keyword argument. You can also select a particular version of the lookup table using the version argument.

By default, agate-lookup will use the wireservice/lookup repository of lookup tables. Look there to see what key/value combinations and versions you can use with lookup.

You can also specify your own repository of lookupt ables by constructing an instance of Source and passing it into the TableLookup.lookup() method.

API

agatelookup.patch()

Patch the features of this library onto agate’s core Table and TableSet.

class agatelookup.table_lookup.TableLookup
lookup(source_keys, value, table_keys=None, version=None, source=None, require_match=False)

Fetch a lookup table from the remote source, matches it this table by its key columns, appends the value column and returns a new table instance.

Parameters:
  • source_keys – A column name or a sequence of such names to match in the lookup table. For example 'naics' or ['city', 'year'].
  • value – The value that is being looked up. For example 'description' or 'population'. This is the column that will be appended.
  • table_keys – A column name or a sequence of such names to match in this table. This defaults the same values specified for source_keys, so it only needs to be specified if the column names in this table don’t match.
  • version – An optional version of the lookup to use, if more than one exists. For instance '2007' for the 2007 edition of the NAICS codes or '2012' for the 2012 version.
  • source

    An instance of Source that defines where lookup tables are located. If not specified a default source will be used that points to the wireservice/lookup repository.

  • require_match – If True, an exception will be raised if there is a value in this table with no matching entry in the lookup table.
class agatelookup.source.Source(root='http://wireservice.github.io/lookup', table_url_func=<function default_table_url_func>, metadata_url_func=<function default_metadata_url_func>, callback=<bound method type.from_csv of <class 'agate.table.Table'>>)

A reference to an archive of lookup tables. This is a remote location with lookup table and metadata files at a known path structure.

Parameters:
  • root – The root URL to prefix all data and metadata paths.
  • table_url_func – A function that takes table metadata and returns an absolute URL to that table’s data file. See default_table_url_func().
  • metadata_url_func – A function that takes table metadata and returns an absolute URL to that table’s data file. See default_metadata_url_func().
  • callback – A function that translates the remote data table into an agate table. Typically this is agate.Table.from_csv(), but it could also be agate.Table.from_json() or a method provided by an extension.
get_metadata(keys, value, version=None)

Fetches metadata related to a specific lookup table.

See Source.get_table() for parameter details.

get_table(keys, value, version=None)

Fetches and creates and agate table from a specified lookup table.

Parameters:
  • keys – Either a single string or a sequence of keys that identify the “left side” of the table. For example 'fips' or ['city', 'year'].
  • value – The value that is being looked up from the given keys. For example 'state' or 'population'.
  • version – An optional version of the given lookup, if more than one exists. For instance '2007' for the 2007 edition of the NAICS codes or '2012' for the 2012 version.

Authors

The following individuals have contributed code to agate-lookup:

Changelog

0.1.0

  • Initial version.

License

The MIT License

Copyright (c) 2016 Christopher Groskopf and contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Indices and tables