codepost_stats.analyzers.abstract package

Submodules

codepost_stats.analyzers.abstract.base module

This submodule contains the abstract interfaces for a codePost statistic analyzer.

The classes implemented here are the parent classes used to build the generic analyzers implemented in the related submodule, codepost_stats.analyzers.abstract.simple, that serve as building blocks for fully implemented analyzers.

Examples of fully-fledged standard analyzers (to do task such as counting the number of submissions graded, or the number of comments authored, etc.), are available in the codepost_stats.analyzers.standard submodule. These can serve as templates illustrating how to implement custom analyzers.

class codepost_stats.analyzers.abstract.base.AbstractAnalyzer

Bases: object

The AbstractAnalyzer class is an abstract class for a codePost analyzer object.

This abstract analyzer class has a number of protected members, such as _event_course(), for each of the different objects within the codePost object model. The analyzer are supposed to be registered with an event loop object, some subclass of codepost_stats.event_loop.AbstractAnalyzerEventLoop; once the event loop is run, it walks through a subset of a codePost course’s data and triggers events in all registered analyzers.

In this way, the analyzer will walk through the codePost data in depth-first search order, which means, for instance, that all submissions of the first assignment will be examined before moving on to the second assignment, and so on.

Some standard analyzers are provided, such as those in the submodule codepost_stats.analyzers.standard, but new ones can easily be authored by overriding one of the provided classes.

Warning

This abstract does not do anything, it is meant to be the least restrictive interface for an analyzer, and is intended to be used mainly as an abstract data type in type signatures.

For most purposes, the BaseAnalyzer class (or a subclass) should be overridden instead.

_event_assignment(*args, **kwargs)

Event triggered when a codePost assignment is visited by an event loop. This event does nothing in this abstract analyzer class.

_event_comment(*args, **kwargs)

Event triggered when a codePost comment is visited by an event loop. This event does nothing in this abstract analyzer class.

_event_course(*args, **kwargs)

Event triggered when a codePost course is visited by an event loop. This event does nothing in this abstract analyzer class.

_event_file(*args, **kwargs)

Event triggered when a codePost file is visited by an event loop. This event does nothing in this abstract analyzer class.

_event_submission(*args, **kwargs)

Event triggered when a codePost submission is visited by an event loop. This event does nothing in this abstract analyzer class.

_name: Optional[str] = None
_normalize_str(s)

Returns a normalized string for purposes of internal string comparisons.

The normalization involves: Returning an empty string if the input parameter is None, otherwise remove leading and trailing spaces, change all alphabetical characters to lowercase, and replace internal spaces with dashes.

Parameters

s (Optional[str]) – A string to be normalized

Returns

The input string s with some transformations

Return type

str

_reset()

Resets the internal state of the analyzer.

Returns

A boolean indicated whether the reset was successful

Return type

bool

property name: str

Get a string representing the analyzer, such as comments.counter.rubric, that can be used when rendering the output of multiple analyzers.

This name is meant to be informative: By default, it is the same for every instance of the analyzer class; and there are no guarantees that it is necessarily unique across all analyzers.

Returns

An internal string describing the analyzer

class codepost_stats.analyzers.abstract.base.BaseAnalyzer

Bases: AbstractAnalyzer

The BaseAnalyzer class is an abstract class for a codePost analyzer object, which expands on the AbstractAnalyzer by providing completed event signatures with the related codePost models; it also keeps track of which course is currently being analyzed.

For most purposes, this is the class that should be overridden to author new analyzer modules, as illustrated in codepost_stats.analyzers.standard.

_course: Optional[Courses] = None
_event_assignment(assignment)

Event triggered when a codePost assignment is visited by an event loop. The course containing the assignment can be accessed through this class’ course attribute.

Parameters

assignment (Assignments) – The codePost assignment

_event_comment(assignment, submission, file, comment)

Event triggered when a codePost comment is visited by an event loop. The course containing the assignment can be accessed through this class’ course attribute.

Parameters

  • assignment (Assignments) – The codePost assignment

  • submission (Submissions) – The codePost submission

  • file (Files) – The codePost file

  • comment (Comments) – The codePost comment

_event_course(course)

Event triggered when a codePost course is visited by an event loop.

Parameters

course (Courses) – The codePost course

_event_file(assignment, submission, file)

Event triggered when a codePost file is visited by an event loop. The course containing the assignment can be accessed through this class’ course attribute.

Parameters

  • assignment (Assignments) – The codePost assignment

  • submission (Submissions) – The codePost submission

  • file (Files) – The codePost file

_event_submission(assignment, submission)

Event triggered when a codePost submission is visited by an event loop. The course containing the assignment can be accessed through this class’ course attribute.

Parameters

  • assignment (Assignments) – The codePost assignment

  • submission (Submissions) – The codePost submission

_name: Optional[str] = None
_reset()

Resets the internal state of the analyzer.

Returns

A boolean indicated whether the reset was successful

Return type

bool

property course: Optional[Courses]

Get the currently analyzed codePost course.

This property is updated by the BaseAnalyzer class when an _event_course() is triggered; if it is accessed before such an event is triggered, the value returned will be None.

Returns

The codepost course being analyzed

property name: str

Get a string representing the analyzer, such as comments.counter.rubric, that can be used when rendering the output of multiple analyzers.

This name is meant to be informative: By default, it is the same for every instance of the analyzer class; and there are no guarantees that it is necessarily unique across all analyzers.

Returns

An internal string describing the analyzer

codepost_stats.analyzers.abstract.simple module

This submodule contains generic analyzer classes that encapsulate common functionality related to the kind of data being tracked, and are supposed to be overridden to create classes such as SubmissionsGradedCounter in codepost_stats.analyzers.standard.

The first generic analyzer is DictStorageAnalyzer, it is designed to record data with two levels of organization, a first level called the name and a second level called the subcat or subcategory. In the above-mentioned example of SubmissionsGradedCounter, for instance, the name would be the login email of the grader and the subcat would be the names of the assignment.

In fact, because there are many scenarii in which one might want to aggregate counts over the codePost data, there is a dedicated generic analyzer for this specific purpose, CounterAnalyzer, which is child class to the DictStorageAnalyzer with an interface specifically designed to keep tally with CounterAnalyzer.add() and CounterAnalyzer.subtract().

class codepost_stats.analyzers.abstract.simple.CounterAnalyzer

Bases: DictStorageAnalyzer

The CounterAnalyzer class is a generic class for a codePost analyzer object, that makes it easy to count statistics (number of submissions graded, comments written, etc.).

This class handles all the initialization and provides two methods, add() and subtract(), to update the internal counters.

Once the analysis is completed, it can be retrieved by iterating over the names attribute, to see all the names for which data has been recorded, and for each name, call the get_by_name() function to retrieve the dictionary of values associated with that name (and divided by subcategories).

This is a high-level analyzer class. The child class codepost_stats.analyzers.standard.SubmissionsGradedCounter provides an example of how to use this class to count the number of submissions graded.

add(name, subcat, delta=1)

Adds to the counter, for the name and subcat record, by relative nonnegative value delta.

This method is implemented by an internal call to _delta_counter(), which is a slightly more powerful method, in particular allowing for arbitrary values of delta.

Parameters

  • name (str) – The name identifier

  • subcat (str) – The subcategory identifier

  • delta (int) – (Optionally) the relative amount by which to adjust the counter

Raises

  • ValueError – If the subcategory subcat does not exist and the subcategory warning is not suppressed

  • ValueError – If the provided delta is negative

Returns

The new value of the counter that has been modified

Return type

int

get_by_name(name, normalize_str=True)

Returns a dictionary of all the values stored associated with name.

Parameters

  • name (str) – The name identifier of the data to query

  • normalize_str (bool) – (Optional) flag to indicate whether to normalize the names of subcategories, using the internal _normalize_str() normalization function

Returns

A dictionary mapping each subcategory to a counter, for the provided name

Return type

Dict[str, int]

subtract(name, subcat, delta=1)

Subtracts from the counter, for the name and subcat record, by relative nonnegative value delta.

This method is implemented by an internal call to _delta_counter(), which is a slightly more powerful method, in particular allowing for arbitrary values of delta.

Parameters

  • name (str) – The name identifier

  • subcat (str) – The subcategory identifier

  • delta (int) – (Optionally) the relative amount by which to adjust the counter

Raises

  • ValueError – If the subcategory subcat does not exist and the subcategory warning is not suppressed

  • ValueError – If the provided delta is negative

Returns

The new value of the counter that has been modified

Return type

int

class codepost_stats.analyzers.abstract.simple.DictStorageAnalyzer

Bases: BaseAnalyzer

The DictStorageAnalyzer class is a generic class for a codePost analyzer object, that stores its output data in a dictionary.

The dictionary storage is designed to contain two levels of organization: The top-level index is a name, such as for instance a grader email address; the secondary index is for a subcategory, for instance an assignment name.

Because this class, like both codepost_stats.analyzers.abstract.base.AbstractAnalyzer and codepost_stats.analyzers.abstract.base.BaseAnalyzer, is not intended to be used directly, many of its fields and methods are private.

property initial_value: _DictValueType

Gets (an immutable copy of) the initial value that is assigned to newly created data cells, before they are first assigned to.

Returns

The initial value assigned to uninitialized cells

property names: List[str]

Gets a list of the names for which data has been recorded since the last reset of the analyzer.

Returns

A list of names for which data has been recorded

Module contents

This submodule provides the abstract interface of a codePost analyzer, as well as some high-level generic analyzers, which seek to identify a few general types of statistics that may be computed on codePost data, so as to limit the amount of redundant code that must be written to support such analyses.

As an example, a typical kind of analysis on codePost data might involve counting the number of occurrences of certain objects (submissions, comments, files, etc.), or the number occurrences of specific types of objects (submissions by grader, comments by recipient, etc.)

This is the purpose of the generic analyzer class codepost_stats.analyzers.abstract.CounterAnalyzer, which contains all the boilerplate code necessary to keep track of many counters over codePost data. This generic analyzer class is then used to provide specialized analyzers such as the following: