pycounter API Docs

pycounter.report module

Commonly-used function

pycounter.report.parse(filename, filetype=None, encoding='utf-8', fallback_encoding='latin-1')

Parse a COUNTER file, first attempting to determine type.

Returns a CounterReport object.

Parameters:

• filename – path to COUNTER report to load and parse.
• filetype – type of file provided, one of “csv”, “tsv”, “xlsx”. If set to None (the default), an attempt will be made to detect the correct type, first from the file extension, then from the file’s contents.
• encoding – encoding to use to decode the file. Defaults to ‘utf-8’, ignored for XLSX files (which specify their encoding in their XML)
• fallback_encoding – alternative encoding to use to try to decode the file if the primary encoding fails. This defaults to ‘latin-1’, which will accept any bytes (possibly producing junk results…) Ignored for XLSX files.

Classes

class pycounter.report.CounterReport(report_type=None, report_version=4, metric=None, customer=None, institutional_identifier=None, period=(None, None), date_run=None, section_type=None)

a COUNTER usage statistics report.

Iterate over the report object to get its rows (each of which is a CounterBook or CounterJournal instance.

Parameters:

• metric – metric being tracked by this report. For database reports (which have multiple metrics per report), this should be set to None.
• report_type – type of report (e.g., “JR1”, “BR2”)
• report_version – COUNTER version
• customer – name of customer on report
• institutional_identifier – unique ID assigned by vendor for customer
• period – tuple of datetime.date objects corresponding to the beginning and end of the covered range
• date_run – date the COUNTER report was generated
• section_type – predominant section type used for this report. (applies to report BR2; should probably be None for any other report type)

as_generic()

Output report as list of lists.

Nested list will contain cells that would appear in COUNTER report (suitable for writing as CSV, TSV, etc.)

write_to_file(path, format_)

Output report to a file.

Parameters:

• path – location to write file
• format – file format. Currently supports ‘tsv’

Returns:

write_tsv(path)

Output report to a COUNTER 4 TSV file.

Parameters:path – location to write file

year

Year report was issued (deprecated).

class pycounter.report.CounterEresource(period=None, metric=None, month_data=None, title='', platform='', publisher='')

Base class for COUNTER statistics lines.

Iterating returns (first_day_of_month, metric, usage) tuples.

Parameters:

• period – two-tuple of datetime.date objects corresponding to the beginning and end dates of the covered range
• metric – metric tracked by this report. Should be a value from pycounter.report.METRICS dict.
• month_data – a list containing usage data for this resource, as (datetime.date, usage) tuples
• title – title of the resource
• publisher – name of the resource’s publisher
• platform – name of the platform providing the resource

class pycounter.report.CounterJournal(period=None, metric='FT Article Requests', issn=None, eissn=None, month_data=None, title='', platform='', publisher='', html_total=0, pdf_total=0, doi='', proprietary_id='')

Statistics for a single electronic journal.

Parameters:

• period – two-tuple of datetime.date objects corresponding to the beginning and end dates of the covered range
• metric – the metric tracked by this statistics line. (Should probably always be “FT Article Requests” for CounterJournal objects, as long as only JR1 is supported.)
• issn – eJournal’s print ISSN
• eissn – eJournal’s eISSN
• month_data – a list containing usage data for this journal, as (datetime.date, usage) tuples
• title – title of the resource
• publisher – name of the resource’s publisher
• platform – name of the platform providing the resource
• html_total – total HTML usage for this title for reporting period
• pdf_total – total PDF usage for this title for reporting period

as_generic()

Get data for this line as list of COUNTER report cells.

class pycounter.report.CounterBook(period=None, metric=None, month_data=None, title='', platform='', publisher='', isbn=None, issn=None, doi='', proprietary_id='', print_isbn=None, online_isbn=None)

statistics for a single electronic book.

Variables:

• isbn – eBook’s ISBN
• issn – eBook’s ISSN (if any)

Parameters:

• month_data – a list containing usage data for this book, as (datetime.date, usage) tuples
• title – title of the resource
• publisher – name of the resource’s publisher
• platform – name of the platform providing the resource

as_generic()

Get data for this line as list of COUNTER report cells.

isbn

Return a suitable ISSN for the ebook.

The tabular COUNTER reports only report an “ISBN”, while the SUSHI (XML) reports include both a Print_ISBN and Online_ISBN.

This property will return a generic ISBN given in the constructor, if any. If the CounterBook was created with no “isbn” but with online_ISBN and/or print_ISBN, the online one, if any, will be returned, otherwise the print.

class pycounter.report.CounterDatabase(period=None, metric=None, month_data=None, title='', platform='', publisher='')

a COUNTER database report line.

as_generic()

Return data for this line as list of COUNTER report cells.

Other functions

These are mostly for internal use by the module, but are available to be called directly if necessary

pycounter.report.format_stat(stat)

Turn numbers possibly with embedded commas into integers.

Also accepts existing ints, which may be pre-converted from Excel.

Parameters:stat – numeric value, possibly with commas Returns:int

pycounter.report.parse_generic(report_reader)

Parse COUNTER report rows into a CounterReport.

Parameters:report_reader – a iterable object that yields lists COUNTER data formatted as tabular lists Returns:CounterReport object

pycounter.report.parse_separated(filename, delimiter, encoding='utf-8', fallback_encoding='latin-1')

Open COUNTER CSV/TSV report and parse into a CounterReport.

Invoked automatically by parse().

Parameters:

• filename – path to delimited COUNTER report file.
• delimiter – character (such as ‘,’ or ‘\t’) used as the delimiter for this file
• encoding – file’s encoding. Default: utf-8
• fallback_encoding – alternative encoding to try to decode if default fails. Throws a warning if used.

Returns:

CounterReport object

pycounter.report.parse_xlsx(filename)

Parse a COUNTER file in Excel format.

Invoked automatically by parse.

Parameters:filename – path to XLSX-format COUNTER report file.

pycounter.sushi module

Note

Before pycounter 1.1, SUSHI requests were always made with SSL verification turned off. The default is now to verify certificates. If you must contact a SUSHI server without verification, please use the verify=False argument to request() or the –no-ssl-verify flag on sushiclient.

Commonly-used function

pycounter.sushi.get_report(*args, **kwargs)

Get a usage report from a SUSHI server.

returns a pycounter.report.CounterReport object.

parameters: see get_sushi_stats_raw

Parameters:no_delay – don’t delay in retrying Report Queued

Other functions

pycounter.sushi.get_sushi_stats_raw(wsdl_url, start_date, end_date, requestor_id=None, requestor_email=None, requestor_name=None, customer_reference=None, customer_name=None, report='JR1', release=4, sushi_dump=False, verify=True, **extra_params)

Get SUSHI stats for a given site in raw XML format.

Parameters:

• wsdl_url – URL to SOAP WSDL for this provider
• start_date – start date for report (must be first day of a month)
• end_date – end date for report (must be last day of a month)
• requestor_id – requestor ID as defined by SUSHI protocol
• requestor_email – requestor email address, if required by provider
• requestor_name – Internationally recognized organization name
• customer_reference – customer reference number as defined by SUSHI protocol
• customer_name – Internationally recognized organization name
• report – report type, values defined by SUSHI protocol
• release – report release number (should generally be 4.)
• sushi_dump – produces dump of XML (or JSON, for COUNTER 5) to DEBUG logger
• verify – bool: whether to verify SSL certificates
• extra_params – extra params are passed to requests.post

pycounter.exceptions module