API reference¶

Objects¶

Comment¶

class sasdocs.objects.comment(text)¶

Bases: sasdocs.objects.baseSASObject

Abstracted python class to reference the SAS comment.

This class recognises SAS code in either of the below forms and stores any texts stored between the comment delimiters in the object’s text attribute.

/* Comment text */
* Comment text;

text¶

Text contained between SAS comment delimiters delimiters

Type: str

Macro Variable¶

class sasdocs.objects.macroVariable(variable)¶

Bases: sasdocs.objects.baseSASObject

Abstracted python class to reference the SAS macro variable.

This class recongises SAS code in the form &variableName. or &variableName where the variable name ‘varaibleName’ is stored in the object’s variable attribute.

variable¶

Macro variable reference as used in SAS code

Type: str

Macro Variable Definition¶

class sasdocs.objects.macroVariableDefinition(variable, value)¶

Bases: sasdocs.objects.baseSASObject

Abstracted python class for the definition and assignment of macro varaibles.

This class recognises SAS %let statements and parses the reference variable and the value assigned to it in to the objects variable and value attributes respectively.

For example

%let var = 1
%let var&i. = 1

Will be parsed into

macroVariableDefinition(variable='var', value='1')
macroVariableDefinition(variable=['var',macroVariable(variable='i')], value='1')

variable¶

Macro variable reference as used in SAS code

Type: str or list

value¶

Unparsed value contained in the macro variable

Type: str or list

Include¶

class sasdocs.objects.include(path)¶

Bases: sasdocs.objects.baseSASObject

Abstracted python class for %include statements in SAS code.

This class recognises SAS %include statements and parses the path assigned to it in to the objects path.

For example

%include "C:/SASCode/Example1.sas"

path¶

Hardcoded path used in the %include statement

Type: str

check_path_is_valid(attribute, value)¶

Set the value of path if parsed path is valid.

Parameters

attribute (str) –
value (str) –

Returns

Return type

None

Libname¶

class sasdocs.objects.libname(library, path, pointer=None)¶

Bases: sasdocs.objects.baseSASObject

Abstracted python class for libname statements.

This object parses a SAS libname statement into the reference variable used in the SAS code and path it defines. In the example below the object’s library attribute is ‘lib1’ and its path attribute is ‘C:/data/’.

In the case that the libname points to an already existing library. The value of path is None and the pointer attribute contains the value of the library being pointed to, in the example below the value of pointer would be ‘lib1’.

libname lib1 "C:/data/";
libname lib2 (lib1);

library¶

libname reference as used in SAS code

Type: str

path¶

Hardcoded path pointing to library on disk

Type: str, optional

pointer¶

Libname reference if current libname is pointing to an already established library

Type: str, optional

type¶

Define whether the libname statement is an explicit path or a pointer

Type: str

uri¶

URL safe version of the path variable

Type: string

check_path_is_valid(attribute, value)¶

Set the value of path if parsed path is valid.

Parameters

attribute (str) –
value (str) –

Returns

Return type

None

Data Object Argument¶

class sasdocs.objects.dataArg(option, setting=None)¶

Bases: sasdocs.objects.baseSASObject

Abstracted python class for an argument applied to a dataset in SAS.

This class recognises inline arguments applied to datasets in SAS code. In the below example this object would pull out the option where with the setting A=1.

data test(where=(A=1));
...

This object is created for each argument in an inline statement and passed to the dataObject options attribute.

option¶

Inline data argument being set

Type: str

settings¶

Value passed to the inline data argument

Type: str

Data Object¶

class sasdocs.objects.dataObject(library, dataset, options=None)¶

Bases: sasdocs.objects.baseSASObject

Abstracted python class for data objects created and used by SAS datasteps and procedures.

This object represents a dataset, as referenced within the SAS code. In the below example there are two dataObjects referenced, foo and bar. Both objects would be generated if this code was parsed by a dataStep parser. As foo has no specified library, its library attribute will default to ‘work’. The bar dataset has an explicit library reference pointing to lib1, this will be the value stored in the library attribute. Any inline options will be parsed into a list and passed to the options attribute.

data foo;
    set lib1.bar;
run;

dataObjects have a name attribute which is the combination of the library and the datastep names seperated by a period. For internal linking they also have a UID attribute which is the upcased version of the name attribute.

library¶

Library in which the data is stored

Type: str or list

dataset¶

Name used to reference the dataset in the code

Type: str or list

options¶

Options applied to the dataset at a particular point

Type: [dataArg]

name¶

String of the form ‘library.dataset’

Type: str

UID¶

Upcased version of ‘library.datastep’, data object’s unique identifier

Type: str

Datastep¶

class sasdocs.objects.dataStep(outputs, inputs, header=None, body=None, options=None)¶

Bases: sasdocs.objects.baseSASObject

Abstracted python class for parsing datasteps

This object represents a datastep process in SAS. In the below example the dataset foo is passed to the object’s output attribute, as parsed into a dataobject object. The dataset bar is parsed into the inputs attribute.

Any addition code, between foo; and the set/merge statment will be saved into the header attribute and similarly any further code between the end of the set/merge statement and the end of the datastep will be parsed into the body attribute. Both the header and body remain as unparsed strings.

data foo;
    set lib1.bar;
run;

outputs¶

List of dataObjects the datastep outputs

Type: list

inputs¶

List of dataObjects the datastep takes as inputs

Type: list

header¶

Any code between the end of the ‘data ;’ statement and the begining of the ‘set/merge ;’ statement

Type: str

body¶

Any code between the end of the ‘set/merge ;’ statement and the ‘run;’ statement

Type: str

options¶

Any options set after the ‘/’ on the datastep. i.e. ‘data test / view=test’.

Type: list

Procedure¶

class sasdocs.objects.procedure(outputs, inputs, type='sql')¶

Bases: sasdocs.objects.baseSASObject

Abstracted python class for parsing procedures.

This object parses a SAS procedure (except proc sql) into inputs, outputs and the type of procedure. The type attribute will capture the word directly after the proc indicator. In a similar way to the datastep parser, the foo and bar datasets will be parsed into the input and outputs respectively.

proc sort data=foo out=bar; by A; run;
proc tranpose data=foo out=bar; by A; var B; run;
proc summary data=foo; class A; output out=bar; run;

outputs¶

List of dataObjects the datastep outputs

Type: list

inputs¶

List of dataObjects the datastep takes as inputs

Type: list

type¶

Procedure type i.e. sort/tranpose/summary

Type: str

Macro start and end flags¶

class sasdocs.objects.macroStart(name, arguments, options=None)¶

Bases: sasdocs.objects.baseSASObject

Flagging class for start of %macro definition

name¶

Name of the %macro being defined

Type: str

arguments¶

List of macroargument objects as defined

Type: list, optional

options¶

List of options set on the macro in the ‘%macro’ line.

Type: list, optional

class sasdocs.objects.macroEnd(text)¶

Bases: sasdocs.objects.baseSASObject

Flagging class for end of %macro definition

text¶

Dummy variable.

Type: str

Macro¶

class sasdocs.objects.macro(ref, arguments, contents, options=None)¶

Bases: sasdocs.objects.baseSASObject

Abstracted python class for SAS macro.

This class parses a SAS macro. In the example below the objects name attribute is ‘run’. The arguments attribute is the parsed arguments defined in the macro variable. The contents attribute is any parseable SAS object found between the end of the %macro statement and the %mend statement.

%macro run(arg1 /*Arg1 docstring*/, arg2=N /*Arg2 docstring*/);
    data &arg1.;
        set &arg2.;
    run;
%mend;

name¶

Name of the marco

Type: str

arguments¶

List of macroarguments parsed from the macro defintion

Type: list, optional

contents¶

List of sasdocs objects parsed within the macro

Type: list

options¶

List of options set on the ‘%macro’ line

Type: list

rawAbout¶

The comments directly after the ‘%macro’ line, analogous to a docstring.

Type: string

documented¶

Indicates whether a docstring has been found

Type: bool

about¶

Cleaned up version of rawAbout, removing SAS comment characters and excessive spacing

Type: string

shortDesc¶

The first 200 characters of about with tabs and new lines removed.

Type: string

Macro Argument¶

class sasdocs.objects.macroargument(arg, default, doc)¶

Bases: sasdocs.objects.baseSASObject

Abstracted python class for parsing a macro argument defintion.

This class parses the marco arguments that are definied in the macro definition. The arg attribute contains the local macro variable name. The default attribute contains the default value defined for the arguement, if no default value is defined then the default attribute is None. Any comments next to the argument definition are parsed and passed to the doc attribute.

In the below example, the arg value is ‘arg1’ and ‘arg2’, the default values are None and ‘N’ and the doc attributes are ‘Arg1 docstring’ and ‘Arg2 docstring’ respectively.

%macro run(arg1 /*Arg1 docstring*/, arg2=N /*Arg2 docstring*/);
...

arg¶

Name of the argument

Type: str

default¶

Default value of the argument

Type: str, optional

doc¶

Documentation comment for the argument

Type: str, optional

Functions¶

flatten_list¶

sasdocs.objects.flatten_list(aList)¶

Recursively dig through a list flattening all none list objects into a single list.

Parameters: aList (list) – List of nested lists and objects to be flattened
Returns: Flattened list containing all objects found in aList
Return type: list

rebuild_macros¶

sasdocs.objects.rebuild_macros(objs, i=0)¶

Recursively generate macro objects from macroStart & macroEnd objects in processed list

Parameters

objs (list) – list of sas objects
i (int) – recursive safe loop variable

Returns

A list of parsed objects with macros rebuilt into single macro objects.

Return type

list

force_partial_parse¶

sasdocs.objects.force_partial_parse(parser, string, stats=False, mark=False)¶

Force partial parse of string skipping unparsable characters

Parameters

parser (parsy.parser) – parsy valid parsing object
string (str) – String to be parsed
stats (bool) – Return percentage parsed if true
mark (bool) – Turn on line:col marking on the parser to identify what point in string the object was parsed at.

Returns

parsed objects from string

Return type

list

Program¶

class sasdocs.program.sasProgram(path)¶

Bases: object

Abstracted SAS program class.

This class represents a .sas program file. Initialised with a valid file path to the .sas file, the parser will then parse any valid SAS object it can find within the file and return them to a list in the contents attribute.

The percentage of complete parsing will also be stored in the parsedRate attribute.

path¶

File path to the source of the SAS program

Type: pathlib.Path

contents¶

List of parsed sasdocs.objects found in the program

Type: list

failedLoad¶

Flag if there was a failure to load/parse the program file

Type: int

raw¶

Raw string version of the program file

Type: str

parsedRate¶

Percentage of the program file successfully parsed

Type: float

build_network()¶: Generate a JSON containing the network diagram for the SAS code and add to class variable self.networkJSON Add class varaible self.hasNodes containing a bool as to whether this code contains any valid data objects.

generate_documentation(template='program.md')¶

Generate documentation for the program using the jinja2 template

Returns: jinja2 templated version of this program
Return type: str

get_data_objects()¶: Loop through all datasteps and procedures and add any valid dataobjects to a list self.dataObjects

get_extended_info()¶

Creates class attributes for extended information about the parsed SAS code.

name : Filename of the SAS code,
path : Full path to the SAS code,
lines : Number of lines in the SAS code,
lastEdit : Timestamp for the last edit of the SAS code,
summary : Counter object returned by summarise_objects,
parsed : Percentage of the SAS code succesfully parsed

get_objects(object=None, objectType=None)¶

Recursively loop through parsed objects in the programs contents, yielding each object. If the object is a macro object, enter and yield sas objects found in the macro’s contents.

This function will never return a macro object.

If passed with optional objectType, this function will only yield objects of type equal to objectType.

Parameters

object (None, macro) – Recursion parameter, if none loop through self.contents else loop through object.contents
objectType (str) – If not none, only yield objects where the object is of type objectType.

Yields

sasdocs.object

load_file(path)¶

Attempt to load the given path and parse into a sasProgram object. Errors logged on failure to resolve path, read file and parse.

Sets values of path, raw, contents and parsed rate if successful.

Parameters: path (str) – Filepath to the SAS file to be parsed.

parse_code_documentation()¶

Generate class variables self.documentation and self.documented containing the first set of comments in the SAS program.

self.documentation: str: The first parsed comments.
self.documented: bool: True if the first object parsed in the SAS code is a comment.

summarise_objects(object=None)¶

Recursively loop through parsed objects in the programs contents, counting each object by object type. This function will count macros and the contents of said macros.

Parameters: object (None, macro) – Recursion parameter, if none loop through self.contents else loop through object.contents
Returns: Collections Counter object for all sasdoc.object types found in program.
Return type: Counter

Project¶

class sasdocs.project.sasProject(path)¶

Bases: object

Abstracted SAS project class.

A SAS project is a collection of individual SAS programs that combine, use the same library, include each other, or generally create datasets used by each other in such away that they can be considered largly part of the same piece of work. …

path¶

File path to the root directory of the project

Type: pathlib.Path

programs¶

List of parsed .sas programs found in the project root or subfolders

Type: [sasProgram]

macroVariables¶

List of all macro variable defintions found in all programs in the project

Type: [macroVariableDefinition]

add_addtional_documentation_to_project()¶

Add any documenation found in the project as an attribute.

Creates readme and documentation attributes.

add_programs_to_project(programPaths)¶

For a list of found paths to .sas files in the project directory, generate sasProgram objects. If any sasProgram objects contain an include object, where possible follow the path in the %include statement, parse file and add to the project’s programs list.

Does not parse the program if the path has already been visited.

Parameters: programPaths (list) – List of discovered program paths in the project’s directories.

generate_documentation(outputDirectory=None)¶: Generate documentation for the project using the jinja2 templates

get_extended_info()¶

Creates class attributes for information about the SAS project.

name : Filename of the SAS code,
path : Full path to the SAS code,
programs : Number of programs found in the project,
summary : Counter object returned by summarise_objects,
objects : Dictionary of Counter objects indexed by program

get_objects(objectType=None)¶

Recursively loop through parsed programs in the project, yielding each sasdocs object. If the object is a macro object, enter and yield sas objects found in the macro’s contents.

This function will never return a macro object.

If passed with optional objectType, this function will only yield objects of type equal to objectType.

Parameters: objectType (str) – If not none, only yield objects where the object is of type objectType.
Yields: sasdocs.object

load_project(path)¶

Search the given path recursively to find all .sas files, then generate sasProgram objects from any valid sas programs found.

Sets values of path and programs.

Parameters: path (str) – The root file path of the project .

summarise_project()¶

summarise_objects()

Recursively loop through parsed objects in the project’s programs, counting each object by object type. This function will count macros and the contents of said macros.

Returns

ObjCounter (Counter) – Collections Counter object for all sasdoc.object types found in all programs in the project.
ProgramCount (dict) – Dictionary containing a object Counter for each program found in the project