Shared

codesectools.shared

Modules:

Name	Description
`cloc`	Provide a wrapper for counting lines of code using the cloc tool.
`cwe`	Handle Common Weakness Enumeration (CWE) data.

cloc

Provide a wrapper for counting lines of code using the cloc tool.

This module contains the Cloc class, a wrapper around the cloc tool, to calculate the number of physical lines of source code for a specific language within a directory.

Cloc

Cloc(dir: Path, lang: str)

A wrapper for the 'cloc' (Count Lines of Code) tool.

Find the 'cloc' executable or download and use the Perl script if the executable is not available but Perl is. Provide a method to count lines of code for a specific language.

Attributes:

Name	Type	Description
`version`	`str`	The version of the cloc Perl script to download.
`cloc_names`	`dict`	A mapping from internal language names to the names used by cloc.
`dir`	`Path`	The directory to run cloc in.
`lang`	`str`	The programming language to count, mapped to the cloc name.
`base_command`	`list[str]`	The command list to execute cloc.

Initialize the Cloc wrapper.

Check for the 'cloc' binary. If not found, check for 'perl' and download the 'cloc.pl' script if it doesn't exist locally.

Parameters:

Name	Type	Description	Default
`dir`	`Path`	The directory to run cloc in.	required
`lang`	`str`	The programming language to count.	required

Methods:

Name	Description
`get_loc`	Get the lines of code for the specified language.

version `class-attribute` `instance-attribute`

version = '2.06'

cloc_names `class-attribute` `instance-attribute`

cloc_names = {'java': 'Java', 'c': 'C'}

dir `instance-attribute`

dir = dir

lang `instance-attribute`

lang = self.cloc_names[lang]

base_command `instance-attribute`

base_command = ['cloc', '.', '--json']

get_loc

get_loc() -> int

Get the lines of code for the specified language.

Execute the cloc command, parse the JSON output, and return the number of source code lines.

Returns:

Type	Description
`int`	The number of lines of code, or 0 if the language is not found
`int`	in the output.

Raises:

Type	Description
`NonZeroExit`	If the cloc command fails.

cwe

Handle Common Weakness Enumeration (CWE) data.

This module downloads the CWE list from cwe.mitre.org if not already cached, and provides classes to access and manage CWE data.

Attributes:

Name	Type	Description
`CWEs`

CWEs `module-attribute`

CWEs = CWEsCollection()

CWE

CWE(
    id: int,
    name: str,
    description: str,
    parent: Self | None = None,
    children: set[Self] | None = None,
)

Represent a single Common Weakness Enumeration.

Attributes:

Name	Type	Description
`id`	`int`	The CWE identifier.
`name`	`str`	The name of the weakness.
`description`	`str`	A description of the weakness.
`parent`	`CWE \| None`	The parent CWE weakness, if any.
`children`	`set[CWE]`	A set of child CWE weaknesses.

Initialize a CWE instance.

Parameters:

Name	Type	Description	Default
`id`	`int`	The CWE identifier.	required
`name`	`str`	The name of the weakness.	required
`description`	`str`	A description of the weakness.	required
`parent`	`Self \| None`	The parent CWE weakness, if any.	`None`
`children`	`set[Self] \| None`	A set of child CWE weaknesses, if any.	`None`

Methods:

Name	Description
`__eq__`	Compare this CWE with another object for equality.
`__hash__`	Return the hash of the CWE instance, based on its ID.
`__repr__`	Return a developer-friendly string representation of the CWE.
`extend`	Retrieve the set of related CWEs within a specified distance in the hierarchy.

id `instance-attribute`

id = id

name `instance-attribute`

name = r.group(1)

full_name `instance-attribute`

full_name = name

description `instance-attribute`

description = description

parent `instance-attribute`

parent = parent

children `instance-attribute`

children = children or set()

eq

__eq__(other: Self | int) -> bool

Compare this CWE with another object for equality.

Parameters:

Name	Type	Description	Default
`other`	`Self \| int`	The object to compare with. Can be another CWE instance or an integer representing the CWE ID.	required

Returns:

Type	Description
`bool`	True if the IDs are equal, False otherwise.

hash

__hash__() -> int

Return the hash of the CWE instance, based on its ID.

repr

__repr__() -> str

Return a developer-friendly string representation of the CWE.

Returns:

Type	Description
`str`	A string showing the class name and CWE ID.

extend

extend(distance: int = 1) -> set[Self]

Retrieve the set of related CWEs within a specified distance in the hierarchy.

Recursively finds parent and child CWEs up to the given distance level. Includes the current CWE in the returned set.

Parameters:

Name	Type	Description	Default
`distance`	`int`	The number of levels to traverse up (parents) and down (children). Defaults to 1.	`1`

Returns:

Type	Description
`set[Self]`	A set of CWE objects including the self and related weaknesses.

CWEsCollection

CWEsCollection()

Manage the collection of all CWEs.

Downloads and loads the official CWE list from a CSV file.

Attributes:

Name	Type	Description
`cwes_data`	`dict`	A mapping of CWE categories to their CSV filenames.
`directory`	`Path`	The path to the cached CWE data directory.
`cwes`	`list[CWE]`	A list of all loaded CWE objects.

Initialize the CWEs collection.

Download the CWE data from cwe.mitre.org if it's not present in the user cache.

Methods:

Name	Description
`download`	Download CWE data from the official MITRE website.
`load`	Load and parse CWE data from cached CSV files.
`from_string`	Get a CWE from a string like 'CWE-79'.
`from_id`	Get a CWE by its identifier.

cwes_data `instance-attribute`

cwes_data = {
    "Software Development": "699.csv",
    "Hardware Design": "1194.csv",
    "Research Concepts": "1000.csv",
}

directory `instance-attribute`

directory = USER_CACHE_DIR / 'cwe'

NOCWE `instance-attribute`

NOCWE = CWE(
    id=-1,
    name="\tMissing or invalid CWE",
    description="None",
)

cwes `property`

cwes: list[CWE]

Get the list of all CWEs, loading them if necessary.

download

download() -> None

Download CWE data from the official MITRE website.

load

load() -> dict[int, CWE]

Load and parse CWE data from cached CSV files.

Reads the CSV files defined in cwes_data, instantiates CWE objects, and establishes parent-child relationships based on the "Related Weaknesses" field.

Returns:

Type	Description
`dict[int, CWE]`	A dictionary mapping CWE IDs (int) to `CWE` objects.

from_string

from_string(cwe_string: str) -> CWE

Get a CWE from a string like 'CWE-79'.

Parameters:

Name	Type	Description	Default
`cwe_string`	`str`	The string representation of the CWE ID.	required

Returns:

Type	Description
`CWE`	The corresponding CWE object, or a default 'Invalid CWE' object if the string is malformed.

from_id

from_id(cwe_id: int) -> CWE

Get a CWE by its identifier.

Parameters:

Name	Type	Description	Default
`cwe_id`	`int`	The integer ID of the CWE to find.	required

Returns:

Type	Description
`CWE`	The CWE object if found, otherwise a default CWE object with ID -1.

Shared

codesectools.shared

cloc

Cloc

dir

lang

version class-attribute instance-attribute

cloc_names class-attribute instance-attribute

dir instance-attribute

lang instance-attribute

base_command instance-attribute

get_loc

cwe

CWEs module-attribute

CWE

id

name

description

parent

children

id instance-attribute

name instance-attribute

full_name instance-attribute

description instance-attribute

parent instance-attribute

children instance-attribute

__eq__

other

__hash__

__repr__

extend

distance

CWEsCollection

cwes_data instance-attribute

directory instance-attribute

NOCWE instance-attribute

cwes property

download

load

from_string

cwe_string

from_id

cwe_id

`dir`

`lang`

version `class-attribute` `instance-attribute`

cloc_names `class-attribute` `instance-attribute`

dir `instance-attribute`

lang `instance-attribute`

base_command `instance-attribute`

CWEs `module-attribute`

`id`

`name`

`description`

`parent`

`children`

id `instance-attribute`

name `instance-attribute`

full_name `instance-attribute`

description `instance-attribute`

parent `instance-attribute`

children `instance-attribute`

eq

`other`

hash

repr

`distance`

cwes_data `instance-attribute`

directory `instance-attribute`

NOCWE `instance-attribute`

cwes `property`

`cwe_string`

`cwe_id`