File: roles.py

package info (click to toggle)
python-stem 1.7.1-1.1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 5,768 kB
  • sloc: python: 29,441; java: 312; makefile: 125; sh: 17
file content (97 lines) | stat: -rw-r--r-- 2,704 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
import re

from docutils.utils import unescape
from docutils.nodes import reference
from docutils.parsers.rst.roles import set_classes


def role_trac(name, rawtext, text, lineno, inliner, options={}, content=[]):
  """
  Aliases :trac:`1234` to 'https://trac.torproject.org/1234'.

  :param name: the role name used in the document
  :param rawtext: the entire markup snippet, with role
  :param text: the text marked with the role
  :param lineno: the line number where rawtext appears in the input
  :param inliner: the inliner instance that called us
  :param options: directive options for customization
  :param content: the directive content for customization
  """

  # checking if the number is valid
  try:
    ticket_num = int(text)

    if ticket_num <= 0:
      raise ValueError
  except ValueError:
    msg = inliner.reporter.error('Invalid trac ticket: %s' % text, line=lineno)
    prb = inliner.problematic(rawtext, rawtext, msg)

    return ([prb], [msg])

  app = inliner.document.settings.env.app
  link_text = 'ticket %s' % unescape(str(ticket_num))

  return (
    [make_link_node(rawtext, app, 'trac_url', link_text, str(ticket_num), options)],
    [],
  )


def role_spec(name, rawtext, text, lineno, inliner, options={}, content=[]):
  """
  Aliases :spec:`25b0d43` to 'https://gitweb.torproject.org/torspec.git/commit/?id=25b0d43'.
  """

  # checking if the input is a valid short commit id

  if not re.match('^[0-9a-f]{7}$', text):
    msg = inliner.reporter.error('Spec tag expects a short commit id (seven hex characters): %s' % text, line=lineno)
    prb = inliner.problematic(rawtext, rawtext, msg)

    return ([prb], [msg])

  app = inliner.document.settings.env.app

  return (
    [make_link_node(rawtext, app, 'spec_url', 'spec', text, options)],
    [],
  )


def make_link_node(rawtext, app, url_type, link_text, slug, options):
  """
  Creates a link to a trac ticket.

  :param rawtext: text being replaced with link node
  :param app: sphinx application context
  :param url_type: base for our url
  :param link_text: text for the link
  :param slug: ID of the thing to link to
  :param options: options dictionary passed to role func
  """

  base_url = getattr(app.config, url_type, None)

  if not base_url:
    raise ValueError("'%s' isn't set in our config" % url_type)

  ref = base_url.format(slug = slug)
  set_classes(options)

  return reference(rawtext, link_text, refuri = ref, **options)


def setup(app):
  """
  Installs the plugin.

  :param app: sphinx application context
  """

  app.add_role('trac', role_trac)
  app.add_config_value('trac_url', None, 'env')

  app.add_role('spec', role_spec)
  app.add_config_value('spec_url', None, 'env')