pycounter API Docs¶
pycounter.report module¶
Commonly-used function¶
-
pycounter.report.
parse
(filename, filetype=None, encoding='utf-8', fallback_encoding='latin-1')[source]¶ 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)[source]¶ a COUNTER usage statistics report.
Iterate over the report object to get its rows (each of which is a
CounterBook
orCounterJournal
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
()[source]¶ Output report as list of lists.
Nested list will contain cells that would appear in COUNTER report (suitable for writing as CSV, TSV, etc.)
-
class
pycounter.report.
CounterEresource
(period=None, metric=None, month_data=None, title='', platform='', publisher='')[source]¶ 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='')[source]¶ 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
-
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)[source]¶ 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
-
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.
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)[source]¶ 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)[source]¶ 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')[source]¶ 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.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)[source]¶ 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)[source]¶ 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