scrummd package

Submodules

scrummd.card module

class scrummd.card.Card(index: str, summary: str, collections: list[str], defined_collections: dict[str, list[str]], path: str, collection_from_path: str, udf: dict[str, FieldStr | list[FieldStr] | FieldNumber], _config: ScrumConfig, parsed_md: ParsedMd)

Bases: object

A Scrum ‘Card’ - might be a chunk of work, might be an epic, might be a ticket.

assert_valid_rules(config: CollectionConfig) → None

Raise an error if a card doesn’t comply with an active configuration

Parameters:

config (ScrumConfig | CollectionConfig) – Current Config to check against

Returns:

None

Raises:

RequiredFieldNotPresentError – A field required by the collection’s required config wasn’t present.
InvalidRestrictedFieldValueError – A field was not set to a valid value per the collections fields config.

collection_from_path: str: Collection that was implied from the path

collections: list[str]: Collections that the card is in

defined_collections: dict[str, list[str]]: Collections that are defined by this card

get_field(field_name: str) → FieldStr | list[FieldStr] | FieldNumber | None

Get a field from either the card if present, or UDF if not

Parameters:: field_name (str) – Field to retrieve
Returns:: Field from Card, UDF if not present, or None if in neither.
Return type:: Optional[Field]

index: str: Index of the card

parsed_md: ParsedMd: The MD with additional metadata

path: str: Path of the file for this card

summary: str: Title of the card - used by default in places like output

udf: dict[str, FieldStr | list[FieldStr] | FieldNumber]: All additional fields in the file

scrummd.card.NON_UDF_FIELDS = ['summary', 'index', 'path']: Fields that are read into the Card itself rather than into the UDF

scrummd.card.assert_valid_fields(config: ScrumConfig, fields: ParsedMd) → None

Raise an error if there is an (internal or config) rule violation

Parameters:

config (ScrumConfig) – ScrumMD Config
fields (dict[str, Field]) – Fields of a card to assess

Raises:

InvalidFileError – There is an issue with the fields that means it is invalid for ScrumMD regardless of configuration.
InvalidRestrictedFieldValueError – A field with restricted permitted values per config has another value present.
RequiredFieldNotPresentError – A field required by the config is not present

scrummd.card.from_parsed(config: ScrumConfig, parsed_md: ParsedMd, collection_from_path: str, path: Path) → Card

Create a card from a parsed MD file (usually, from a file via extract_fields)

Parameters:

config (ScrumConfig) – ScrumMD configuration to use.
parsed_md (ParsedMd) – The ParsedMd file to create the card with
collection_from_path (str) – Collection from the relative path
path (Path) – Path of the file

Raises:

InvalidFileError – Error with the MD file
InvalidRestrictedFieldValueError – A field with restricted permitted values per config has another value present.
RequiredFieldNotPresentError – A field required by the config is not present

Returns:

The card for the md file

Return type:

Card

scrummd.card.from_str(config: ScrumConfig, input_card: str, collection_from_path: str, path: Path) → Card

Create a card from a string (usually, the file)

Parameters:

config (ScrumConfig) – ScrumMD configuration to use.
input_card (str) – String containing the card data from the file.
collection_from_path (str) – Collection the card is known to be from the relative path.
path (Path) – Path of the file

Raises:

InvalidFileError – Error with the MD file
InvalidRestrictedFieldValueError – A field with restricted permitted values per config has another value present.
RequiredFieldNotPresentError – A field required by the config is not present

Returns:

The card for the md file

Return type:

Card

scrummd.collection module

class scrummd.collection.Filter(field: str, values: str | list[str], mode: FilterMode = FilterMode.EQUALS)

Bases: object

Filter for filtering through a collection

class FilterMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Types of filter

EQUALS = 1

Apply this filter to a collection

Parameters:: collection (Collection) – Collection to apply the filter to
Returns:: The filtered collection
Return type:: Collection

field: str: Field that is being tested

mode: FilterMode = 1: Mode that the filter is in

values: str | list[str]: Potential values for the field

class scrummd.collection.Group(groups: 'Groups', collection: collections.OrderedDict[str | scrummd.source_md.FieldStr | list[scrummd.source_md.FieldStr] | scrummd.source_md.FieldNumber, scrummd.card.Card])

Bases: object

collection: OrderedDict[str | FieldStr | list[FieldStr] | FieldNumber, Card]

groups: OrderedDict[str | FieldStr | list[FieldStr] | FieldNumber | None, Group]

class scrummd.collection.SortCriteria(key: str, reversed: bool)

Bases: object

Fields and order to sort by

key: str: Field name to sort by

reversed: bool: Reverse the order of the collection

Apply all filters to a collection

Parameters:

collection (Collection) – Collection to apply filters to.
filters (list[Filter]) – Filters to apply. All filters are applied.

Returns:

Filtered collection of cards.

Return type:

Collection

scrummd.collection.get_collection(config: ScrumConfig, collection_name: str | None = None) → OrderedDict[str | FieldStr | list[FieldStr] | FieldNumber, Card]

Get a collection of cards

Parameters:

config (ScrumConfig) – ScrumMD Configuration to use
collection_name (Optional[str], optional) – Collection to return. Defaults to None (being All).

Raises:

DuplicateIndexError – A card with an index is found twice

Returns:

A dict with the index of the card, and a card object

Return type:

dict[str, Card]

Group collection into (potentially nested) groups by the field in the Card, sorted if required

Parameters:

config (ScrumConfig) – Scrum config
collection (Collection) – Collection of cards to group
groups (list[str]) – All the groups that need to be made
sort_criteria (list[SortCriteria]) – Criteria to sort the groups and cards by

Returns:

A dict with the group value, and either more groups or the field value

Return type:

Groups

Sort a collection of cards by the sort criteria

Parameters:

collection (Collection) – Collection to sort
criteria (list[SortCriteria]) – Criteria to sort by

Returns:

Sorted collection of cards

Return type:

SortedCollection

scrummd.config module

The ScrumConfig class to configure processing scrum files.

class scrummd.config.CollectionConfig(fields: dict[str, list[str]] = <factory>, required: list[str] = <factory>)

Bases: object

Configuration for any specific collection of cards

fields: dict[str, list[str]]: Fields with limited permitted values and defined order

required: list[str]: Fields that are required to be in a card

class scrummd.config.SblConfig(columns: list[str] = <factory>, default_group_by: str | None = None, omit_headers: bool = False)

Bases: object

Configuration specific to sbl

columns: list[str]: List of columns to return in output

default_group_by: str | None = None: Default group-by for sbl

omit_headers: bool = False: Omit headers from output

class scrummd.config.SboardConfig(columns: list[str] = <factory>, default_group_by: str | None = None)

Bases: object

Configuration specific to sboard

columns: list[str]: List of columns to return in output

default_group_by: str | None = None: Default group-by for sboard

class scrummd.config.ScardConfig(default_template: str | None = 'default_scard.j2')

Bases: object

Configuration specific to scard

default_template: str | None = 'default_scard.j2': Default jinja2 template to use for scard output

class scrummd.config.ScrumConfig(fields: dict[str, list[str]] = <factory>, required: list[str] = <factory>, scrum_path: str = 'scrum', strict: bool = False, collections: dict[str, ~scrummd.config.CollectionConfig | dict[str, list[str] | str]] = <factory>, scard: ~scrummd.config.ScardConfig = <factory>, sbl: ~scrummd.config.SblConfig = <factory>, sboard: ~scrummd.config.SboardConfig = <factory>, allow_header_summary: bool = False)

Bases: CollectionConfig

The configuration that applies to all cards and ScrumMD

allow_header_summary: bool = False

collections: dict[str, CollectionConfig | dict[str, list[str] | str]]: Embedded collection config

sbl: SblConfig

sboard: SboardConfig

scard: ScardConfig

scrum_path: str = 'scrum': Base path for the scrum folder

strict: bool = False: Fail on any error with the scrum folder (such as duplicate index or invalid file)

scrummd.config_loader module

Code for loading the config from the filesystem

scrummd.config_loader.load_fs_config() → ScrumConfig: Load the config from the filesystem into a ScrumConfig

scrummd.const module

scrummd.exceptions module

exception scrummd.exceptions.DuplicateIndexError(index, path)

Bases: RuleViolationError

Raised when an index of a card is declared twice in the collection.

exception scrummd.exceptions.FieldNotPresentError(field: str, index: str | None = None)

Bases: ModificationError

Raised when a field that should be modified isn’t present.

exception scrummd.exceptions.ImplicitChangeOfTypeError

Bases: ModificationError

Raised when the existing type of a field (list, property, block) no longer supports the new value.

exception scrummd.exceptions.InvalidFileError

Bases: ValidationError

Raised if the file is not a valid scrummd md file

exception scrummd.exceptions.InvalidGroupError

Bases: ValueError

Raised when a field is not a valid group

exception scrummd.exceptions.InvalidRestrictedFieldValueError

Bases: RuleViolationError

Raised if there’s a field with defined values, and a value in a file that isn’t in those defined values

exception scrummd.exceptions.ModificationError

Bases: Exception

Errors raised that prevent modification.

exception scrummd.exceptions.NotAListError(field: str, index: str | None = None)

Bases: ImplicitChangeOfTypeError

Raised when attempting to modify a list… that’s not a list.

exception scrummd.exceptions.RequiredFieldNotPresentError

Bases: RuleViolationError

Raised when a field required by config isn’t present

exception scrummd.exceptions.RuleViolationError

Bases: ValidationError

Raised if there is a validation of one of the rules for this scrum repo

exception scrummd.exceptions.TemplateNotFoundError(filename, searched_paths)

Bases: FileNotFoundError

Raised when a template file can’t be found.

exception scrummd.exceptions.UnsupportedModificationError

Bases: ModificationError

Raised when a field can’t be modified.

exception scrummd.exceptions.ValidationError

Bases: ValueError

Raised if there’s a failure validating a card that’s being built

exception scrummd.exceptions.ValuesNotPresentError(values: list[str], field: str, index: str | None = None)

Bases: ModificationError

Raised when a field isn’t present that is to be removed.

scrummd.formatter module

Tools for getting templates, and formatting a card with them to output

scrummd.formatter.DEFAULT_MD_TEMPLATE = 'default_md.j2': The default MD template

class scrummd.formatter.TemplateFields(config: ScrumConfig, card: Card, cards: Collection, interactive: bool, groups: list[tuple[FIELD_GROUP_TYPE, list[str]]], meta: dict[str, FieldMetadata])

Bases: object

Fields to pass to the template

card: Card: The card being formatted.

cards: Collection: The full collection of cards.

config: ScrumConfig: The relevant ScrumMD config.

groups: list[tuple[FIELD_GROUP_TYPE, list[str]]]: Ordered keys groups by their block type in the md file.

interactive: bool: Whether the command is being run in an interactive terminal.

meta: dict[str, FieldMetadata]: Metadata from the fields of original source md.

scrummd.formatter.format(config: ScrumConfig, template_filename: str, card: Card, collection: Collection) → str

Format the card with the named template.

Parameters:

config (scrummd.config.ScrumConfig) – Scrum Config
template_filename (str) – Name of template
card (Card) – Card to format
collection (Collection) – Collection of cards

Returns:

Card formatted per template

Return type:

str

scrummd.formatter.format_from_str(config: ScrumConfig, template: str, card: Card, collection: Collection) → str

Format a card with the provided template.

Parameters:

config (scrummd.config.ScrumConfig) – Scrum Config
template (str) – Template to use
card (Card) – Card to format
collection (Collection) – Collection of cards

Returns:

Card formatted per template

Return type:

str

scrummd.formatter.load_template(filename: str, config: ScrumConfig) → Template

Load the template (using path rules) from the filename.

Tries to find the file in the following order:

The file in the current directory
The file in the .templates directory in the scrum_path
The file in the templates directory in the scrum_path
The module resources

Parameters:

filename (str) – Filename of template to load
config (scrummd.config.ScrumConfig) – Scrum Config

Returns:

Compiled Jinja2 Template

Return type:

jinja2.Template

scrummd.sbench module

Generate a collection, and time accessing it for benchmarking common scrummd functions.

scrummd.sbench.create_parser() → ArgumentParser

Return argument parser for sbench

Returns:: Parser for sbench
Return type:: ArgumentParser

scrummd.sbench.entry(): Entry point for sbench

scrummd.sbench.rand_str(size: int, whitespace: bool = False)

scrummd.sbench.scrum_repo(count: int, references: int, minsize: int, sortcount: int) → Iterator[ScrumConfig]

Create a temporary folder full of cards

Parameters:

count (int) – Amount of files to generate
references (int) – Amount of card references to add to each card
minsize (int) – Min size of each card in bytes
sortcount (int) – Amount of sort criteria to apply

Returns:

The ScrumConfig to load files with

Return type:

ScrumConfig

scrummd.sbl module

scrummd.scard module

Display any number of scrum cards

scrummd.scard.create_parser() → ArgumentParser

Create an argument parser for scard

Returns:: Argument parser to use
Return type:: ArgumentParser

scrummd.scard.entry(args=None, config=None): Entry point for scard

scrummd.scard.format_field(value: FieldStr | list[FieldStr] | FieldNumber | None) → str

Format a given field for output

Parameters:: value (Optional[Field]) – Field to output
Raises:: TypeError – Field is not a recognised formattable type
Returns:: Field suitable to use in output
Return type:: str

scrummd.scard.output_cards(config: ScrumConfig, template: str, collection: OrderedDict[str | FieldStr | list[FieldStr] | FieldNumber, Card], card_indexes: list[str] | str)

Output cards to stdout

Parameters:

config (ScrumConfig) – Current configuration
collection (Collection) – Complete collection of cards
card_index (list[str]) – Indexes of cards to output

scrummd.source_md module

class scrummd.source_md.CardComponent(card_index: str, card: Card | None = None)

Bases: FieldComponent

A component of the field that refers to a card

card: Card | None = None: The referred to card

card_index: str: The index of the card

class scrummd.source_md.CodeBlockComponent(value: str)

Bases: FieldComponent

A component that is a block of pre-formatted code.

value: str

class scrummd.source_md.CodeQuoteComponent(value: str)

Bases: FieldComponent

A component that is a small piece of pre-formatted code as part of another line.

value: str

class scrummd.source_md.FIELD_GROUP_TYPE(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Type of group these fields are in

HEADER_BLOCK = (2,)

IMPLICIT_SUMMARY = 3

PROPERTY_BLOCK = (1,)

UNSET = (0,)

class scrummd.source_md.FIELD_MD_TYPE(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

How the field appears in the md file itself

BLOCK = 2

IMPLICIT = 0

IMPLICIT_SUMMARY = 5

LIST_HEADER = 4

LIST_PROPERTY = 3

PROPERTY = 1

scrummd.source_md.Field = scrummd.source_md.FieldStr | list[scrummd.source_md.FieldStr] | scrummd.source_md.FieldNumber: A field from the md file

class scrummd.source_md.FieldComponent

Bases: object

A section of the field component

class scrummd.source_md.FieldMetadata(md_type: FIELD_MD_TYPE, raw_field_name: str, header_level: int)

Bases: object

Metadata for a field

Stores the logical type of the field, as well as the original field name.

header_level: int: The amount of #’s (or lines under) of the header

md_type: FIELD_MD_TYPE: The physical type of the field, as it appears in the md file

raw_field_name: str: The original field name, as it appears in the md file.

class scrummd.source_md.FieldNumber(x=0, /)

Bases: float, FieldComponent

A float with the extra parsed information

class scrummd.source_md.FieldStr(value)

Bases: str

A str with the extra parsed information from the str

components(collection: Collection) → list[FieldComponent]

Break the field string into its components. This can be used for when the card is outputted to - for instance - format the strings.

Returns:: All the components of the str.
Return type:: list[FieldComponent]

extract_collection() → list[str]

Extract all of the card ids from a field (str or list of strings).

Cards marked with ! (like [[!c1]]) are no included.

Returns:: list[str] A list of all card indexes.

class scrummd.source_md.ParsedMd

Bases: object

A dictionary of the MD with additional metadata from the md file

add_to_list(config: ScrumConfig, field: str, values: list[str]) → ParsedMd

Add an item to a field list, returning a new ParsedMd

Parameters:

config (ScrumConfig) – The config to use for type checking..
field (str) – The field to add to.
values (list[str]) – The values to add to the field.

Raises:

NotAListError – Raised when the field to be written to is not a list.
FieldNotPresentError – Raised when the field is not present in the file.

append_field(raw_key: str, value: FieldStr | list[FieldStr] | FieldNumber, md_type: FIELD_MD_TYPE, header_level: int = 1) → None

Add a field to the field dictionary, storing its location in metadata.

Parameters:

key (str) – The key of the field to add.
value (Field) – The value of the field to add.
md_type (FIELD_MD_TYPE) – The type of the field in the md file.

copy() → ParsedMd

Creates a new ParsedMd with the same fields and metadata.

Returns:: A new ParsedMd with the same fields and metadata.
Return type:: ParsedMd

insert_field(raw_key: str, value: FieldStr | list[FieldStr] | FieldNumber, md_type: FIELD_MD_TYPE, index: int, header_level: int = 1) → None

Add a field to the field dictionary, storing its location in metadata.

Parameters:

key (str) – The key of the field to add.
value (Field) – The value of the field to add.
md_type (FIELD_MD_TYPE) – The type of the field in the md file.
index (int) – The index to insert the field at.

items() → ItemsView[str, FieldStr | list[FieldStr] | FieldNumber]

Exposes the field dict items().

Returns:: The items of the field dict.
Return type:: list[tuple[str, Field]]

keys() → KeysView[str]

Exposes the field dict keys().

Returns:: The keys of the field dict.
Return type:: list[str]

keys_grouped_by_field_md_type() → list[tuple[FIELD_GROUP_TYPE, list[str]]]

Field IDs grouped by the blocks of data types in the original source.

Used for recreating the md file from scratch. Property/Property Lists are included in the same group. It’s possible to have multiple groups of the same type of field (for instance - if there’s multiple property blocks)

Returns:: Ordered groups, with ordered lists of keys.
Return type:: list[list[key]]

meta(key: str) → FieldMetadata

Returns the metadata for a field.

Parameters:: key (str) – The key of the field to get the metadata of.
Returns:: The metadata of the field.
Return type:: FieldMetadata

order() → list[str]

Returns the order of the fields.

Returns:: The order of the fields.
Return type:: list[str]

remove_field(key: str) → None

Remove a field from the field dictionary.

Parameters:: key (str) – The key of the field to remove.

remove_from_list(config: ScrumConfig, field: str, values: list[str]) → ParsedMd

Remove an item from a field list, returning a new ParsedMD. Multiple matching items will result in only the first being removed.

Parameters:

config (ScrumConfig) – The config to use for type checking..
field (str) – The field to add to.
values (list[str]) – The (case insensitive) values to remove from the field.

Raises:

NotAListError – Raised when the field to be written to is not a list.
FieldNotPresentError – Raised when the field is not present in the file.
ValuesNotPresentError – Raised when the value is not present in the list to remove.

set_fields(config: ScrumConfig, fields_to_set: list[tuple[str, str]]) → ParsedMd

Sets all fields in fields_to_set to their respective values (creating them if they don’t: exist. Returns a new ParsedMd with the new value.

Parameters:

config (ScrumConfig) – The config to use for type checking.
fields_to_set (list[tuple[str, str]]) – Fields to set or create. Each change is in the form of (FieldToChange, ValueToSetItTo).

class scrummd.source_md.StringComponent(value: str)

Bases: FieldComponent

A component of the field that is just a string.

value: str

scrummd.source_md.extract_collection(field_value: FieldStr | list[FieldStr] | FieldNumber) → list[str]

Extract all of the card ids from a field (str or list of strings)

Parameters:: field_value (Field) – Field from the md file
Returns:: A list of all card indexes
Return type:: list[Index]

scrummd.source_md.extract_fields(config: ScrumConfig, md_file: str) → ParsedMd

Extract all fields from the md_file

There are two types of fields: - ‘Property’ style fields - ‘md header’ style fields:

There are two types of value: - Strings - Lists

Lists are defined as items in a list of items starting with ‘-’ and ending with a newline following the header or property.

All keys are case insensitive and made lowercase.

Parameters:: md_file (str) – Contents of file to get data out of
Returns:: a dictionary of all field names and values
Return type:: dict[str, Field]

scrummd.source_md.get_raw_block_name(md_line: str) → str

Get the name of the block from the header line

Parameters:: md_line (str) – Line to remove any preceeding ‘#’s from

Returns: str: Text of header

scrummd.source_md.split_list_item(md_line: str) → str

Return the ‘value’ part of a list, stripping the bullet

Parameters:: md_line (str) – Line to split
Returns:: Output after ‘-’
Return type:: str

scrummd.source_md.split_property(md_line: str) → tuple[str, str]

Split the property into its key and value

Parameters:: md_line (str) – Line in the format of “key: value” to split
Returns:: Key and value
Return type:: tuple(str, str)

scrummd.source_md.typed_field(field: str) → FieldStr | list[FieldStr] | FieldNumber

Return a Field of an appropriate type from the string

Currently supports strings and numbers - not lists.

Parameters:: field (str) – Field value to interpret
Returns:: A correctly typed field
Return type:: Field

scrummd.svalid module

Return an exit code if there’s any invalid files, or rules being broken.

Returns: 0 if Successful; 1 if Exception Raised; 2 if Invalid File; 3 if Rules Violation.

class scrummd.svalid.ExitCode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

INVALID_FILE = 2

OTHER_FAILURE = 1

RULE_VIOLATION = 3

SUCCESSFUL = 0

scrummd.svalid.create_parser() → ArgumentParser

Create an argument parser for svalid

Returns:: ArgumentParser for svalid
Return type:: argparse.ArgumentParser

scrummd.svalid.entry() → None: Entry point

scrummd.svalid.get_exit_code(config: ScrumConfig) → ExitCode

Return what the exit code should be

Returns:: Validation status of the repository
Return type:: ExitCode

scrummd.swrite module

Set fields of a card

scrummd.swrite.create_parser() → ArgumentParser

Create an argument parser for sprop

Returns:: ArgumentParser for sprop
Return type:: argparse.ArgumentParser

scrummd.swrite.entry(injected_args: List[str] | None = None, config: ScrumConfig | None = None, stdin: StringIO | None = None, stdout: StringIO | None = None) → None: Entry point

scrummd package

Submodules

scrummd.card module

scrummd.collection module

scrummd.config module

scrummd.config_loader module

scrummd.const module

scrummd.exceptions module

scrummd.formatter module

scrummd.sbench module

scrummd.sbl module

scrummd.scard module

scrummd.source_md module

scrummd.svalid module

scrummd.swrite module

scrummd.template module

Module contents