castanet 1.3.0

Program to identify different syntax markers in Python programs

CASTanet

Table of Contents

• About CASTanet

• Installing CASTanet

• Running CASTanet

• CASTanet's Command Line Interface

• Testing

• Contributions

• Contact Us

About CASTanet

CASTanet is a tool created by students at Allegheny College, allowing users to understand the contents of Python (.py) files. Through using concrete abstract syntax trees (CASTs), a combination of abstract syntax trees (ASTs) and concrete syntax trees (CSTs), CASTanet uses LibCST to reorganize and name node types and fields. CASTanet has functionality to iterate through a user-specified directory and generate metrics associated with the Python files in that given directory. This tool can be used by educators interested in evaluating students' code, or individual developers who would like to better understand their own implementation strategies.

Currently, CASTanet is able to count:

• Number of if statements in a Python file (and total in directory)
• Number of looping constructs in a Python file (and total in directory)
• Number of comments in a Python file (and total in directory)
• Number of arguments for a specified Python function
• Number of functions in a specified Python file (and total in directory)
• Number of function definitions without docstrings in a Python file (and total in directory)
• Number of classes in a Python file (and total in directory)
• Number of class definitions without docstrings in a Python file (and total in directory)
• Number of assignment statements in a Python file (and total in directory)
• Whether a specified function has a docstring or not
• Number of import statements in a Python file (and total in directory)

Installing CASTanet - PyPI

Run the command to install: pip install castanet

Installing CASTanet - Repository

Clone the CASTanet repository onto your machine

In the appropriate directory, clone the CASTanet repository following GitFlow and the GitHub documentation

Install Poetry and dependencies

The documentation and instructions on installing Poetry can be found here.

Poetry allows dependency installation with ease. After cloning the CASTanet repository, and installing Poetry, install all necessary dependencies for the tool with the command:

poetry install

Running CASTanet

CASTanet is a fully-functional tool with a dynamic command line interface, built with the user in mind. To run the CASTanet CLI, in the base directory of your local, cloned repository and type the command:

castanet [command-here]

Without specifying a command, you will receive this error in your terminal:

Usage: castanet [OPTIONS] COMMAND [ARGS]...
Try 'castanet --help' for help.

Error: Missing command.

Please refer to the next section to see what functionality CASTanet has, and what commands to run.

CASTanet's Command Line Interface

CASTanet's command line interface is created with Typer, a library for building CLI applications based on Python 3.6+ type hints.

In order to familiarize yourself with the commands for CASTanet, run the command: poetry run castanet --help

CASTanet's commands are as follows:

PLEASE NOTE: Each of the following commands must be run with the file path of the directory of interest given as input. This directory must be present on your machine, and CASTanet will provide output pertaining to this specified directory.

castanet assignments

Determine number of assignment statements.

Usage:

castanet assignment [OPTIONS] PATH

Arguments:

• PATH: [required]

castanet total-classes

Determine number of classes without docstrings.

Usage:

castanet total-classes [OPTIONS] PATH

Arguments:

• PATH: [required]

castanet classes-without-docstrings

Determine number of classes without docstrings.

Usage:

castanet classes-without-docstrings [OPTIONS] PATH

Arguments:

• PATH: [required]

castanet comments

Determine number of comments.

Usage:

castanet comments [OPTIONS] PATH

Arguments:

• PATH: [required]

castanet function-arguments

Determine the number of parameters for a given function.

Usage:

castanet function-arguments [OPTIONS] PATH FUNCTION_NAME

Arguments:

• PATH: [required]
• FUNCTION_NAME: [required]

castanet function-docstring-exists

Determine if a given function has a docstring.

Usage:

castanet function-docstring-exists [OPTIONS] PATH FUNCTION_NAME

Arguments:

• PATH: [required]
• FUNCTION_NAME: [required]

castanet functions-without-docstrings

Determine number of functions without docstrings.

Usage:

castanet functions-without-docstrings [OPTIONS] PATH

Arguments:

• PATH: [required]

castanet if-statements

Determine number of if statements in a Python directory.

Usage:

castanet if-statements [OPTIONS] PATH

Arguments:

• PATH: [required]

castanet imports

Determine number of import statements.

Usage:

castanet imports [OPTIONS] PATH

Arguments:

• PATH: [required]

castanet looping-constructs

Determine number of looping constructs.

Usage:

castanet looping-constructs [OPTIONS] PATH

Arguments:

• PATH: [required]

castanet functions-per-module

Determine number of functions in a Python directory.

Usage:

castanet functions-per-module [OPTIONS] PATH

Arguments:

• PATH: [required]

castanet total-functions

Determine total number of functions in a Python directory.

Usage:

castanet total-functions [OPTIONS] PATH

Arguments:

• PATH: [required]

Currently, CASTanet only has functionality for one metric to be calculated at a time. As a result, if you are interested in one or more metric, you must run CASTanet for the first metric (with the corresponding CLI command), and then run CASTanet subsequently for each additional metric (with the corresponding CLI command).

CASTanet as a Python Library

CASTanet is also available on PyPI to be used as a Python library. Find it here. With the CASTanet library, a user is able to investigate their Python files with many different function calls. Specifically, CASTanet is broken down into two parts:

1. generate_trees: Traverses a directory and generates concrete-abstract-syntax trees of Python files using LibCST
2. counter: Uses concrete-abstract-syntax-trees to calculate metrics associated with the contents of a Python module

counter

from castanet import counter

sum_dict_vals

Calculate the sums of values from dictionaries. Called to get number values from the result of a function. Must always be run on the results of count functions to get final numbers.

counter.sum_dict_vals(values_dict)

ARGUMENTS:

• values_dict: dictionary of total values for metrics

RETURNS:

• int: total number of items in dictionary

count_imports

Count the number of import statements in a Python file.

counter.count_imports(path)

ARGUMENTS:

• path: A string path corresponding to a Python file or a directory

RETURNS:

• dict: files and the corresponding amount of import statements

count_functions

Count the number of function definitions in a Python file.

counter.count_functions(path)

ARGUMENTS:

• path: A string path corresponding to a Python file or a directory

RETURNS:

*dict: files and the corresponding amount of function definitions

count_comments

Count the number of comments in a Python file.

counter.count_comments(path)

ARGUMENTS:

• path: A string path corresponding to a Python file or a directory

RETURNS:

• dict: files and the corresponding amount of comments

count_while_loops

Count the number of while loops in a Python file.

counter.count_while_loops(path)

ARGUMENTS:

• path: A string path corresponding to a Python file or a directory

RETURNS:

• dict: files and the corresponding amount of while loops

count_for_loops

Count the number of for loops in a Python file.

counter.count_for_loops(path)

ARGUMENTS:

• path: A string path corresponding to a Python file or a directory

RETURNS:

• dict: files and the corresponding amount of for loops

count_if_statements

Count the number of if statements in a Python file.

counter.count_if_statements(path)

ARGUMENTS:

• path: A string path corresponding to a Python file or a directory

RETURNS:

• dict: files and the corresponding amount of if statements

count_func_defs

Count the number of function definitions in a Python file.

counter.count_func_defs(path)

ARGUMENTS:

• path: A string path corresponding to a Python file or a directory

RETURNS:

• dict: files and the corresponding amount of function_definitions

count_function_without_docstrings

Count the number of functions without docstrings.

counter.count_function_without_docstrings(func_count)

ARGUMENTS:

• dict: A dictionary of functions and docstring counts per file

RETURNS:

• int: total number of functions - total number of docstrings

Note: It is required to first call count_func_defs in order for this function call to work correctly.

docstring_exists

Determine if a docstring exists for a specified function.

counter.docstring_exists(path, function_name)

ARGUMENTS:

• path: A string path corresponding to a Python file or a directory
• function_name (str): Name of function to check for docstrings

RETURNS:

• -1: function does not exist
• 0: function exists without docstring
• 1: function exists with docstring

match_class_defs

Count the number of class definitions in a Python file.

counter.count_class_defs(cast_dict)

ARGUMENTS:

• path: A string path corresponding to a Python file or a directory

RETURNS:

• dict: files and the corresponding amount of class definitions

count_class_defs_without_docstrings

Count the number of class definitions without docstrings.

counter.count_class_defs_without_docstrings(class_count)

ARGUMENTS:

• dict: A dictionary of classes and docstring counts per file

RETURNS:

• int: total number of classes - total number of docstrings

Note: It is required to first call count_class_defs in order for this function call to work correctly.

count_function_arguments

Count the number of arguments for a specified function.

counter.count_function_arguments(path, function_name)

ARGUMENTS:

• path: A string path corresponding to a Python file or a directory
• function_name: User-specified file of interest

RETURNS:

• -1: Function was not found
• else: The amount of parameters for the given function

count_assignments

Count the number of assignment statements in a Python file.

(does not include augmented assignment)

counter.count_assignments(path)

ARGUMENTS:

• path: A string path corresponding to a Python file or a directory

RETURNS:

• dict: files and the corresponding amount of assignment statements

count_aug_assignment

Count the number of aug assignment statements (x += 5) in a Python file.

counter.count_aug_assignment(path)

ARGUMENTS:

• path: A string path corresponding to a Python file or a directory

RETURNS:

• dict: files and the corresponding amount of aug assignment statements

Testing

Automated Testing

Developers of this program can run the test suite with Pytest with the command:

poetry run task test

Contributions

We welcome everyone who is interested in helping to improve CASTanet! If you are interested in being a contributor, please review our Code of Conduct and Guidelines for Contributors before raising an issue, or beginning a contribution.

To raise an issue in CASTanet's Issue Tracker please follow these templates:

• bug_report.md

• feature_request.md

To create a pull request, please follow this template:

• pull_request_template.md

Contact Us

If you have any questions or concerns about CASTanet, please contact:

• Madelyn Kapfhammer ([e-mail])
• Thomas Antle ([e-mail])
• Nolan Thompson ([e-mail])
• Caden Hinckley ([e-mail])
• Bailey Matrascia ([e-mail])