Next / Previous / Contents / NM Tech homepage

5. Using the pycbc interface

To access this database from a Python script, import the pycbc module and call the CBCData() constructor like this:

import pycbc

db = pycbc.CBCData(password)

If you pass the correct database password as an argument, you will be granted read-write access; otherwise any attempt to retrieve data will fail.

5.1. The CBCData class

Here are the attributes and methods on this class.

.engine

The sqlalchemy.engine.Engine instance connecting to the Postgresql engine where the CBC database lives.

.meta

The schema as a sqlalchemy.schema.MetaData instance.

This is not documented in the SQLAlchemy reference materials, but a MetaData instance contains a .tables attribute that is a dictionary whose keys are the names of mapped tables, and each corresponding value is the actual Table instance for that table.

.Session

A constructor for an SQLAlchemy session.

.s

A Session instance. Use this only for single-threaded applications. For multi-threaded applications, create a new Session for each thread.

.Nation

The mapped class for the nations table. See Section 5.2, “The Nation class”.

.Region

The mapped class for the regions table. See Section 5.3, “The Region class”.

.Physio

The mapped class for the physios table. See Section 5.4, “The Physio class”.

.Circle

The mapped class for the circles table. See Section 5.5, “The Circle class”.

.Effort

The mapped class for the efforts table. See Section 5.6, “The Effort class”.

.Census

The mapped class for the censuses table. See Section 5.7, “The Census class”.

.nations_table, .regions_table, .physios_table, .circles_table, .efforts_table, .census_table

The actual Table instances.

.genNations()

Generate a sequence of the Nation instances in ascending order by nation name.

.getNation(nationCode)

Return the Nation instance with a given nation code. Will raise KeyError if there is no such code.

.genRegions()

Generate a sequence of the Region instances in ascending order by region name.

.getRegion(regionCode)

Return the Region instance with a given region code, or raise KeyError if there is no such code.

.genPhysios()

Generate the Physio instances in self, in ascending order by code.

.getPhysio(code)

Return the Physio instance for a given physiographic stratum code, or raise KeyError if it is not found.

.getRegionCircle(regionCode, cirName)

If there is a circle whose name is exactly cirName and occurs all or partly in the region whose code is regionCode, return the corresponding Circle object, otherwise raise KeyError.

.genCircles()

Generates the Circle instances in ascending order by latitude + longitude.

.genCirclesByName(prefix)

Generates all the Circle instances whose names begin with the given prefix, in ascending order by circle name.

.genRegionCircles(regionCode)

Generate Circle instances for all the circles that occur in any part of the region with a given code, in ascending order by circle name.

.genPrimaryRegionCircles(regionCode)

Generate Circle instances for all the circles that are listed under the region with a given code; that is, the circles for which the given region code is the first one displayed. To find all the circles that occur even partially in a given region, use the .circles attribute of a Region instance.

.genCirclesByPhysio(physioCode)

Generate all the Circle instances that are associated with the physiographic stratum whose code is physioCode.

.getCircle(lat, lon)

Given a latitude as a string "ddmm" and a longitude as "dddmm", return the corresponding Circle instance. If that center is not in the database, the method will raise a KeyError.

.genEfforts()

Generate all the Effort records in self in primary key order.

.overlappers(fromCircle)

Use this method to find other circles that overlap a given Circle instance fromCircle. The return value is a list of tuples (pct, c) where pct is the percentage of their areas that overlap, in the open interval (0.0,100.0), and c is the overlapping Circle instance, and the list is in descending order by the pct value.

.getEffort(year_no, year_key)

Returns the Effort instance for the given year number and year key.