API

High Level API

crc_diagram.to_crc(fp, parser_class=PythonParser, **parser_class_kwargs)

Shortcut to PythonParser(fp).parse().result.

Param:file|str fp: The file to extract the CRCs. Can be either a file path as string or a file like object. Param:BaseParser parser_class: The parser class. Param:tuple allowed_file_extensions: Any file extension which is not in this list will be ignored. Param:parser_class_kwargs: additional keyword arguments to parser_class Returns:A list of CRCs

Example:

to_crc('html_to_markdown.py')

Will return:

[
CRC(name=HtmlToMarkdown,
    kind=class,
    collaborators=['ImageUploader'],
    responsibilities=['Convert html files to markdown']
),
CRC(name=ImageUploader,
    kind=class,
    collaborators=[],
    responsibilities=['Store images in the cloud'])
]

crc_diagram.folder_to_crc(path, parser_class=PythonParser, **parser_class_kwargs)

Iterate in all files in path and call to_crc to each one.

Parameters:

• path (str) – The folder path.
• parser_class (BaseParser) – The parser class.

Param:

tuple allowed_file_extensions: Any file extension which is not in this list will be ignored.

Param:

parser_class_kwargs: additional keyword arguments to parser_class

Returns:

A list of CRCs of all files in path.

Example:

from os.path import join

folder = join('crc_diagram', 'testing', 'files', 'python_project')
folder_to_crc(folder)

And the result:

[
CRC(name=Student,
   kind=class,
   collaborators=['Enrollment'],
   responsibilities=['Validate Identifying info', 'Provide list of seminars taken']
),
CRC(name=Seminar,
    kind=class,
    collaborators=['Student', 'Professor'],
    responsibilities=['List transcripts',
                      'Drop student',
                      'Add student',
                      'Get enrolled students']
),
# ...

Core

class crc_diagram.core.CRC(name, kind='class', collaborators=None, responsibilities=None)

Class that represents a CRC Card.

Parameters:

• name (str) – The name of the class.
• kind (str) – The kind of the CRC. Default is ‘class’
• collaborators (list) – A list of strings containing the collaborators.
• responsibilities (list) – A list of strings containing the responsibilities.

Example:

crc = CRC('HtmlToMarkdown',
          kind='class',
          collaborators=['ImageUploader'],
          responsibilities=['Convert html to markdown']
      )

crc.to_dict()

And the result:

{
    'collaborators': ['ImageUploader'],
    'name': 'HtmlToMarkdown',
    'kind': 'class',
    'responsibilities': ['Convert html to markdown']
}

to_dict()

Return a dict representation of the instance attributes.

Parsers

class crc_diagram.core.parsers.PythonParser(stream, responsibility_pattern, collaborator_pattern)

A parser class which extracts CRC data from docstrings using ast module.

Parameters:

• path_or_stream – A file path or a file like object from where the CRCs will be extracted.
• collaborator_pattern (regular_expression) – A regex pattern do extract the collaborators from docstrings. The default is COLLABORATOR_PATTERN.
• responsibility_pattern (regular_expression) – A regex pattern do extract the responsibilities from docstrings. The default is RESPONSIBILITY_PATTERN.
• allowed_file_extensions (tuple) – A list of file extensions do accept. The parser will ignore any files which extension isn`t in this list.

Example:

parser = PythonParser('file.py').parse()
parser.result

The result is a list of CRC instances:

[
    CRC(name='HtmlToMarkdown',
        kind='class',
        collaborators=['ImageUploader'],
        responsibilities=['Convert html files to markdown']
        ),
    CRC(name='ImageUploader',
        kind='class',
        collaborators=[],
        responsibilities=['Store images in the cloud']
        )
]

You can change the patterns used to extract responsibilities and collaborators passing a regular expression to PythonParser:

responsibility_pattern = r'\s*?:responsibility:(.*)$'

parser = PythonParser(
            'file.py',
            responsibility_pattern=responsibility_pattern
        )

This will extract any data in docstring which has the following format:

:responsibility: Save the world

The same is valid to collaborators:

collaborator_pattern = r'\s*?:collaborator:(.*)$'

parser = PythonParser(
            'file.py',
            collaborator_pattern=collaborator_pattern
        )

And you also can pass re.compile objects:

import re

collaborator_pattern = re.compile(r'\s*?:collaborator:(.*)$')

parser = PythonParser(
            'file.py',
            collaborator_pattern=collaborator_pattern
        )

parse()

The main functionality. It parses a tree from self.path_or_stream and uses ast.NodeVisitor to iterate over the tree.

Returns:self

Renders

class crc_diagram.renders.DotRender(crc_cards, format='png', graph_data=None)

Render CRC cards using DOT language.

Parameters:

• crc_cards (list) – A list of CRC objects.
• format (str) – The format used to save the diagram. Default is png.
• graph_data (dict) – graph attributes, see documentation here.

Example:

from crc_diagram import py_to_crc

# getting crcs from a file
crcs = py_to_crc('html_to_markdown.py')

DotRender(crcs).render('html_to_markdown.png')

This will save to html_to_markdown.png the diagram

You can open it passing view=True to render method:

DotRender(crcs).render('html_to_markdown.png', view=True)

By default DotRender uses a directed graph.

You can customize the graph passing a dictionary to graph_data=graph_data:

# create a blue graph
graph_data = {
    'fillcolor': 'blue',
    'style': 'filled'
}

DotRender(crcs, graph_data=graph_data).render(
    'html_to_markdown.png',
    view=True
    )

Rendered diagram:

create_edges(crc)

Iterate over crc.collaborators and create a edge for each one if the edge hasn’t already been created.

Parameters:crc (CRC) – A CRC instance.

edge_already_added(crc_name, collaborator)

Return True if a edge have already been added for that collaborator return False otherwise.

Parameters:

• crc_name (str) – The CRC name.
• collaborator (str) – The CRC collaborator.

get_edge_direction(collaborator, crc_name)

Check if a collaborator has bidirectional reference:

A -> B
B -> A

Parameters:

• collaborator (str) – The collaborator to check against.
• crc_name (str) – The name of the CRC to check against.

Return direction:  

both if the collaborator has bidirectional reference or single otherwise.

render(filename, view=False)

Render self.graph.

Parameters:

• filename (str) – The filename where the diagram will be saved.
• view (bool) – Set to True to open the rendered diagram.

source

Returns the DOT source of the self.graph

Exceptions

class crc_diagram.exceptions.ParserException

Raised when something goes wrong while parsing source files to CRCs.

Next >>