summaryrefslogtreecommitdiff
path: root/creole/setup_utils.py
blob: 0fe1e2412164663652e2bbe57fe930c580dc6c70 (plain)
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
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
"""
    Python setup.py utilities
    ~~~~~~~~~~~~~~~~~~~~~~~~~

    Generate ReStructuredText README from README.creole.
    Usable for other python packages, too.

    More information:
        https://github.com/jedie/python-creole/wiki/Use-In-Setup

    :copyleft: 2011-2020 by the python-creole team, see AUTHORS for more details.
    :license: GNU GPL v3 or above, see LICENSE for more details.
"""

import codecs
import datetime
import os
import sys
import warnings
from pathlib import Path

from creole import creole2html, html2rest
from creole.shared.diff_utils import unified_diff
from creole.shared.unknown_tags import raise_unknown_node, transparent_unknown_nodes


RAISE_ERRORS_ARGS = (
    'check', 'register', 'sdist', 'bdist', 'upload',
    '--long-description', '--restructuredtext',
)


def should_raise_errors():
    """
    Raise only errors, if one of RAISE_ERRORS_ARGS is in sys.argv
    or if no argument presents.
    """
    if len(sys.argv) == 1:
        return True

    for arg in RAISE_ERRORS_ARGS:
        if arg in sys.argv:
            return True
    return False


def get_long_description(package_root, filename='README.creole', raise_errors=None):
    """ read README file and convert it on-the-fly to ReStructuredText. """

    warnings.warn('get_long_description() will be removed in the future', DeprecationWarning)

    if raise_errors is None:
        raise_errors = should_raise_errors()

    if raise_errors:
        sys.stderr.write('Test creole2rest and raise an error, if rendering failed...\n')
        # raise a error if a unknown node found
        unknown_emit = raise_unknown_node
    else:
        # ignore unknown nodes
        unknown_emit = transparent_unknown_nodes

    filepath = os.path.join(package_root, filename)
    long_description_origin = ''
    try:
        # Read creole README
        f = codecs.open(filepath, 'r', encoding='utf-8')
        long_description_origin = f.read().strip()
        f.close()

        # convert creole into html
        long_description_html = creole2html(long_description_origin)

        # convert html to ReSt
        long_description_rest = html2rest(
            long_description_html,
            emitter_kwargs={'unknown_emit': unknown_emit}
        )
    except Exception:
        if raise_errors:
            raise
        # Don't raise the error e.g. in ./setup install process
        evalue = sys.exc_info()[1]
        long_description_rest = f'[Error: {evalue}]\n{long_description_origin}'
    else:
        if raise_errors:
            # Test created ReSt code like PyPi does it.
            from creole.rest_tools.pypi_rest2html import pypi_rest2html
            try:
                pypi_rest2html(long_description_rest)
            except SystemExit as e:
                msg = f'Error creole2rest self test failed: rest2html() exist with status code: {e.args[0]}\n'
                sys.stderr.write(msg)
                sys.exit(msg)
            except Exception as e:
                sys.exit(f'ReSt2html error: {e}')
            else:
                if 'check' in sys.argv:
                    print('Generating creole to ReSt to html, ok.')

    return long_description_rest


def _generate_rst_readme(*, creole_readme_path):
    with creole_readme_path.open('r') as f:
        creole_readme = f.read().strip()

    # convert creole into html
    html_readme = creole2html(creole_readme)

    # convert html to ReSt
    rest_readme = html2rest(
        html_readme,
        emitter_kwargs={
            'unknown_emit': raise_unknown_node  # raise a error if a unknown node found
        }
    )
    return rest_readme


def update_rst_readme(package_root, filename='README.creole'):
    """
    Generate README.rst from README.creole
    """
    assert isinstance(package_root, Path)
    assert package_root.is_dir(), f'Directory not found: {package_root}'
    creole_readme_path = Path(package_root, filename)
    assert creole_readme_path.is_file(), f'File not found: {creole_readme_path}'

    rest_readme_path = creole_readme_path.with_suffix('.rst')
    print(
        f'Generate {rest_readme_path.name} from {creole_readme_path.name}',
        end='...', flush=True
    )

    rest_readme = _generate_rst_readme(creole_readme_path=creole_readme_path)

    with rest_readme_path.open('w') as f:
        f.write(rest_readme)

        # Add a note about generation with modification time from source:

        f.write('\n\n------------\n\n')

        modification_time = creole_readme_path.stat().st_mtime
        dt = datetime.datetime.fromtimestamp(modification_time)
        dt = dt.replace(microsecond=0)
        dt = dt.isoformat(sep=' ')
        f.write(f'``Note: this file is generated from {filename} {dt} with "python-creole"``')

    print('done.')
    return rest_readme_path


def assert_rst_readme(package_root, filename='README.creole'):
    """
    raise AssertionError if README.rst is not up-to-date.
    """
    creole_readme_path = Path(package_root, filename)
    rest_readme = _generate_rst_readme(creole_readme_path=creole_readme_path)
    rest_readme_path = creole_readme_path.with_suffix('.rst')
    with rest_readme_path.open('r') as f:
        content = f.read()

    assert len(content) > 0, f'Empty content in {rest_readme_path}'
    content = content.rsplit('\n', 4)[0]  # remove note about generation with modification time

    if rest_readme != content:
        diff = unified_diff(content, rest_readme, filename=rest_readme_path.name)
        raise AssertionError(f'{rest_readme_path.name} is not up-to-date:\n{diff}')


def update_creole_rst_readme():
    return update_rst_readme(
        package_root=Path(__file__).parent.parent,
        filename='README.creole'
    )


if __name__ == '__main__':
    update_creole_rst_readme()