References and reference parsing

class proclamation.types.Reference(item_type, number, service_params)

A simple class storing the information about a reference.

A reference is an issue, merge/pull request, ticket number, etc: any known namespace of identifiers that suit your project. By customizing your template (or, in extreme cases, your reference parser) you can accommodate a variety of project structures split across multiple systems.

Generally created from a string by ReferenceParser.

If you customize Proclamation by writing your own customized subclass of ReferenceParser, you do not necessarily have to use this class. However, for most project structures, even fairly complicated ones, this class and a custom template suffice.

as_tuple()

Return all contents as a tuple for use in sets and maps.

Required of all classes that are to be used as a reference, for de-duplication.

Don’t actually use this in your templates!

item_type

Item type, like issue, mr, pr.

number

Reference number.

service_params

A list/tuple of any additional parameters associated with the service.

class proclamation.types.ReferenceParser

The base class and default “reference parser”.

If you choose to customize this functionality, inherit from it. Otherwise, use it as-is.

Reference parsers may use the Reference class from this module, as this one does, but it’s not required. Whatever suits you best is fine as long as it works with your template.

References are things like ticket numbers, issue numbers, merge/pull request numbers, etc. This portion of the system is left fairly flexible since there are almost as many project administration structures as there are projects.

make_reference(elts)

Convert a list/tuple of elements into a reference.

This might be the only function you need to override if you need a custom reference parser but can deal with the filename being .-delimited.

Called by parse_filename() and parse() once they’ve separated the parts of their input string.

>>> ReferenceParser().make_reference(['mr', '50', 'extradata'])
Reference('mr', 50, ['extradata'])

>>> ReferenceParser().make_reference(['mr', '50'])
Reference('mr', 50, [])

>>> ReferenceParser().make_reference(['mr', '50', 'extradata',
...                                   'evenmoredata'])
Reference('mr', 50, ['extradata', 'evenmoredata'])

This list is not a valid reference: not enough elements.

>>> ReferenceParser().make_reference(['mr'])

This list is not a valid reference: can’t convert the second element to a number.

>>> ReferenceParser().make_reference(['mr', 'fifty'])

parse(s)

Turn a string into a reference or None.

This will drop a file extension if it’s present, but does not require it to be present unlike parse_filename().

May override or extend.

>>> ReferenceParser().parse("mr.50.md")
Reference('mr', 50, [])

>>> ReferenceParser().parse("mr.50.extradata.md")
Reference('mr', 50, ['extradata'])

>>> ReferenceParser().parse("mr.50")
Reference('mr', 50, [])

>>> ReferenceParser().parse("mr.50.extradata")
Reference('mr', 50, ['extradata'])

parse_filename(s)

Turn a filename string into a reference or None.

Unlike parse(), this method requires that the string end in one of the known file extensions, as a way to avoid accidentally loading files that aren’t meant to be changelog fragments.

May override or extend.

>>> ReferenceParser().parse_filename("mr.50.md")
Reference('mr', 50, [])

>>> ReferenceParser().parse_filename("mr.50.extradata.md")
Reference('mr', 50, ['extradata'])

This should return None because there’s no file extension.

>>> ReferenceParser().parse_filename("mr.50")

This should return None because there’s no (recognized) file extension.

>>> ReferenceParser().parse_filename("mr.50.extradata")

split_on_dot_and_drop_ext(s)

Return the .-delimited portions of a name/ref, excluding a file extension, and whether or not a file extension was removed.

This is a utility function used by both parse() and parse_filename().

>>> ReferenceParser().split_on_dot_and_drop_ext("mr.50.md")
(['mr', '50'], True)

>>> ReferenceParser().split_on_dot_and_drop_ext("mr.50.extradata.md")
(['mr', '50', 'extradata'], True)

>>> ReferenceParser().split_on_dot_and_drop_ext("mr.50")
(['mr', '50'], False)

>>> ReferenceParser().split_on_dot_and_drop_ext("mr.50.extradata")
(['mr', '50', 'extradata'], False)

unparse(ref: Reference) → str

Turn a Reference back into a string.

May override or extend.

>>> rp = ReferenceParser()
>>> rp.unparse(rp.parse("mr.50.md"))
'mr.50'

>>> rp.unparse(rp.parse("mr.50.extradata"))
'mr.50.extradata'

>>> rp.unparse(rp.parse("mr.50.extradata.more"))
'mr.50.extradata.more'