stl Internals

Overview

stl performs the core operations of the stl suite:

• collects word count data from project files.
• caches and maintains word count data (in /tmp) to prevent overreacting of unchanged data.
• integrates with sauron to provide logging and notification.

Dependencies

stl depends on the following system tools:

• wc
• grep
• sed
• find

Additionally, it uses the following python modules:

Internal Modules

sauron

Standard Library Modules

• os.path
• subprocess
• argparse

Implementation

stl.shell_word_count(directory, extension='txt')

Parameters:

• directory (string) – The path of the top level directory that contains the project’s documents. Pass in as a string.
• extension (string) – The file extension, without the preceding period (i.e. .) of all project files. All project files must have an extension. stl only counts the words in files that have this extension.

Returns:

The word count for the project files in the specified directory.

stl.wc_message_builder(project, directory, force=None, extension=None)

Parameters:

• project (string) – The name of the project. stl uses this string to report and track the word count for a specific project, to avoid over-reporting, and to annotate logs.
• directory (string) – The path of the top level directory that contains the project’s documents. Pass in as a string.
• force (bool) – When true, always return the word count, even if the word count value is the same as the cached value.
• extension – The file extension, without the preceding period (i.e. .) of all project files. All project files must have an extension. stl only counts the words in files that have this extension.

wc_message_builder() is the main point of integration between the parts of the script that collect and process the word count data (i.e. wc_message() and shell_word_count()) and sauron() that handles and produces the notification and logging.

Not intended for direct use.

stl.wc_message(word_count, project)

Parameters:

• word_count (string) – The word count value as a string.
• project (string) – The name of the project.

Returns:

A string with a formed word count message used by wc_message_builder().

stl.generate_events(project, directory, target, quiet=False, log=False, emacs=True, force=False, extension=None)

Parameters:

• project (string) – The name of the project. Used to store the cached word count values.
• directory (string) – The path of the directory that holds the project files.
• target (string) – The name of the emacs daemon to send the notification to. If None, does not send notifications.
• quiet (bool) – If True, suppresses output (on standard output.) Defaults to False.
• log (bool) – If True write output to the log. Uses the sauron.NotificationMessage.log() method. Defaults to False.
• emacs (bool) – If True send the Sauron notification. Defaults to True.
• force (bool) – If True passes force=True to wc_message_builder(), which impels reporting, even when the current value is the same as the cached value
• extension (string) – The extension of the project files, to limit reporting to only relevant project files. If None, the default, generate_events() does not pass the extension parameter to shell_word_count().

stl.cli()

Defines and describes the command line interface provided by argparse. See stl Manual for full documentation of this interface.

stl.main()

Logically the flow of data through the methods in stl is:

1. data from cli() passes in from the user into the generate_events().
2. generate_events() calls wc_message_builder(), and if wc_message_builder() returns data, then generate_events() creates and distributes notifications.
3. wc_message_builder() calls shell_word_count() to return the word count, and then uses wc_message() to format and return the word count message to generate_events() where all of the main action is.

Extension and Improvement

• Data generated by stl could be pre-aggregated in some way (running totals, daily progress, etc.), or collected in some system more easily analyzed.
• For projects stored in git, some information about commit, update (i.e. pull) events or branch context, might provide some basic insight when reviewing stl logs. While each system logs to its own log file, some sort of centralization or synchronizing of log data may be useful.