Skip to content

Commit 9a3c40e

Browse files
roskakoriroskakori
authored
Merge pull request #26 from roskakori/25-clean-up-documentation
#25 Clean up documentation
2 parents 577168e + ea97783 commit 9a3c40e

File tree

5 files changed

+178
-147
lines changed

5 files changed

+178
-147
lines changed

‎CHANGES.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Changes
2+
3+
## Version 2.0.0, 2026-02-23
4+
5+
This is a pure technical release that does not change the functionality of the package.
6+
7+
It ensures that the package builds with a modern Python toolchain and continuous integration systems. For details, see [#8](https://github.com/roskakori/CodecMapper/issues/8), contributed by [Branch Vincent](https://github.com/branchv)). In addition, it cleans up some source files missing from the distribution (see [#17](https://github.com/roskakori/CodecMapper/issues/17)) and several minor issues in the documentation.
8+
9+
Because of this, support for Python 2 and Python 3.8 or older had to be dropped. If you are stuck with such a version, use [ebcdic 1.1.1](https://pypi.org/project/ebcdic/1.1.1/), which currently has the same functionality.
10+
11+
In addition, the documentation has been cleaned up to better conform to the standard layout of modern open source projects (see [#25](https://github.com/roskakori/CodecMapper/issues/25):
12+
13+
- The list of changes is now a separate `CHANGES.md` instead of part of the `ebcdic/README.md`.
14+
- The `CONTRIBUTING.md` now includes all the instructions to build the package and run tests. Before, they were spreadout accross the different `README` files.
15+
- The main `README.md` is a concise overview pointing to the other parts of the documentation for details.
16+
17+
## Version 1.1.1, 2019-08-09
18+
19+
- Moved license information from README to LICENSE (#5). This required the distribution to change from sdist to wheel because apparently it is a major challenge to include a text file in a platform independent way (#11).
20+
21+
Sadly this breaks compatibility with Python 2.6, 3.1, 3.2 and 3.3. If you still need `ebcdic` with one of these Python versions, use `ebcdic-1.0.0`.
22+
23+
This took several attempts and intermediate releases that where broken in different ways on different platforms. To prevent people from accidentally installing one of these broken releases they have been removed from PyPI. If you still want to take a look at them, use the [respective tags](https://github.com/roskakori/CodecMapper/releases).
24+
25+
## Version 1.0.0, 2019-06-06
26+
27+
- Changed development status to "Production/Stable".
28+
- Added international code pages cp500ms and cp1148ms which are the Microsoft interpretations of the respective IBM code pages. The only difference is that 0x1f is mapped to 0x85 ("next line") instead of 0x0a ("new line"). Note that codecs.cp500 included with the Python standard library also uses the Microsoft interpretation (#4).
29+
- Added Arabian bilingual code page 420.
30+
- Added Baltic code page 1112.
31+
- Added Cyrillic code page 1025.
32+
- Added Eastern Europe code page 870.
33+
- Added Estonian code pages 1122 and 1157.
34+
- Added Greek code page 875.
35+
- Added Farsi Bilingual code page 1097.
36+
- Added Hebrew code page 424 and 803.
37+
- Added Korean code page 833.
38+
- Added Meahreb/French code page 425.
39+
- Added Japanese (Katakana) code page 290.
40+
- Added Thailand code page 838.
41+
- Added Turkish code page 322.
42+
- Added Ukraine code page 1123.
43+
- Added Python 3.5 to 3.8 as supported versions.
44+
- Improved PEP8 conformance of generated codecs.
45+
46+
## Version 0.7, 2014-11-17
47+
48+
- Clarified which codecs are already part of the standard library and that these codecs overrule the `ebcdic` package. Also added a function `ebcdic.ignored_codec_names()` that returns the name of the EBCDIC codecs provided by other means. To obtain access to `ebcdic` codecs overruled by the standard library, use `ebcdic.lookup()`.
49+
- Cleaned up (PEP8, `__all__`, typos, ...).
50+
51+
## Version 0.6, 2014-11-15
52+
53+
- Added support for Python 2.6+ and 3.1+ (#1).
54+
- Included a modified version of `gencodec.py` that still builds maps instead of tables so the generated codecs work with Python versions earlier than 3.3. It also does a `from __future__ import unicode_literals` so the codecs even work with Python 2.6+ using the same source code. As a side effect, this simplifies building the codecs because it removes the the need for a local copy of the cpython source code.
55+
56+
## Version 0.5, 2014-11-13
57+
58+
- Initial public release

‎CONTRIBUTING.md‎

Lines changed: 94 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,123 @@
1-
## Developer cheat sheet
1+
# Contributing
2+
3+
This document describes how to work with the source code both for the generic CodecMapper and the Python ebcdic package.
4+
5+
## Getting the source code
6+
7+
To work with the source code, clone the repository:
8+
9+
```console
10+
$ git clone https://github.com/roskakori/CodecMapper.git
11+
```
12+
13+
## CodecMapper
14+
15+
### Requirements
16+
17+
To build and run CodecMapper, you need:
18+
19+
1. Java 1.7 or later
20+
2. ant 1.8 or later, available from https://ant.apache.org/.
21+
22+
It might also work with earlier versions of ant, but this has not been tested.
23+
24+
### Usage
25+
26+
To build CodecMapper, run:
27+
28+
```console
29+
$ ant dist
30+
```
31+
32+
To generate a mapping file for a specific codec run, for example:
33+
34+
```console
35+
$ java -jar dist/CodecMapper.jar iso-8859-15
36+
```
37+
38+
The resulting mapping file is stored in `iso-8859-15.txt`. The generated mapping files are located in the same folder and have names like `iso-8859.15.mapping`.
39+
40+
## Python ebcdic package
41+
42+
As an example usage, CodecMapper includes the Python ebcdic package, which is located in the `ebcdic` folder. For general information about this package, take a look at the [ebcdic/README](ebcdic/README.md).
43+
44+
### Requirements
45+
46+
Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
47+
48+
Then set up the pre-commit hooks that will lint the source code before a git commit:
49+
50+
```console
51+
uv run pre-commit install
52+
```
53+
54+
### Building and testing
55+
56+
To build the Python codecs and run the tests:
57+
58+
```console
59+
$ ant test
60+
```
61+
62+
After that, the build artifacts are located in `ebcdic/dist`.
63+
64+
## Adding more codecs
65+
66+
To add another 8-bit EBCDIC codec, extend the ant target `ebcdic` in `build.xml` using a line like:
67+
68+
```xml
69+
<arg value="cpXXX" />
70+
```
71+
72+
Replace `XXX` by the number of the 8-bit code page you want to include.
73+
74+
Then run:
75+
76+
```bash
77+
ant test
78+
```
79+
80+
to build and test the distribution.
81+
82+
## Adding a new release
283

384
Bump version number:
485

586
1. Possibly update copyright year in:
687

7-
- `ebcdic/__init__.py`
8-
- `LICENSE.txt` and
9-
- `README.md`
88+
- `ebcdic/__init__.py`,
89+
- `ebcdic/README.md`,
90+
- `LICENSE.txt`, and
91+
- `README.md`.
1092

1193
2. Edit `ebcdic/_version.py:__version__`.
12-
3. Describe changes in `README.md`.
94+
3. Describe changes in `CHANGES.md`.
1395

14-
Upload release to PyPI::
96+
Upload a release to PyPI:
1597

1698
```console
1799
$ git checkout master
18100
$ git pull
19101
$ ant test
20102
$ cd ebcdic
103+
$ rm -rf dist
21104
$ uv build
22105
$ uv publish
23106
```
24107

25-
Update production branch::
108+
Update production branch:
26109

27110
```console
28111
$ git checkout production
29112
$ git merge master
30113
$ git push
31114
```
32115

33-
Tag a release::
116+
Tag a release:
34117

35118
```console
36-
$ git tag -a -m "Tagged version 1.x.x." v1.x.x
119+
$ git tag --annotate --message "Tagged version 2.x.x." v2.x.x
37120
$ git push --tags
38121
```
122+
123+
Finally, add the [GitHub release](https://github.com/roskakori/CodecMapper/releases/new).

‎LICENSE.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Copyright (c) 2013 - 2019, Thomas Aglassinger
1+
Copyright (c) 2013 - 2026, Thomas Aglassinger
22
All rights reserved.
33

44
Redistribution and use in source and binary forms, with or without

‎README.md‎

Lines changed: 13 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,28 @@
11
# CodecMapper
22

3-
CodecMapper derives mapping files from Java Charsets which can be processed
4-
by Python's gencodec.py.
3+
CodecMapper derives mapping files from Java Charsets which can be processed by Python's gencodec.py.
54

6-
## Requirements
5+
The source code includes everything to build the Python [ebcdic](https://pypi.org/project/ebcdic/) package.
76

8-
To build and run CodecMapper, you need:
9-
10-
1. Java 1.7 or later
11-
2. ant 1.8 or later, available from https://ant.apache.org/.
12-
13-
It might also work with earlier versions of ant but this has not been tested.
14-
15-
## Usage
16-
17-
To build CodecMapper, run:
18-
19-
```sh
20-
$ ant dist
21-
```
22-
23-
To generate a mapping file for a specific codec, run for example:
24-
25-
```sh
26-
$ java -jar dist/CodecMapper.jar iso-8859-15
27-
```
28-
29-
The resulting mapping file is stored in `iso-8859-15.txt`. The generated mapping files
30-
are located in the same folder and have names like
31-
`iso-8859.15.mapping`.
32-
33-
## EBCDIC codecs for Python
34-
35-
As an example usage, CodecMapper can provide additional EBCDIC codecs for
36-
Python, which can easily be packaged and distributed.
7+
## Source code
378

38-
To test the Python codecs, first install [uv](https://docs.astral.sh/uv/getting-started/installation/).
39-
After that you can build the Python codecs and run the tests:
9+
The source code is available from https://github.com/roskakori/CodecMapper.
4010

41-
```sh
42-
$ ant test
43-
```
11+
Refer to [CONTRIBUTING.md](CONTRIBUTING.md) about how to...
4412

45-
For more information, browse the "ebcdic" folder of this distribution and
46-
take a look at the [README](ebcdic/README.md).
13+
- ... build CodecMapper,
14+
- ... extract codecs with it,
15+
- ... build the Python `ebcdic` package,
16+
- ... add more codes to the `ebcdic` package,
17+
- ... to release a new version.
4718

48-
## Source code
19+
## Release history
4920

50-
See https://github.com/roskakori/CodecMapper.
21+
See [CHANGES.md](CHANGES.md).
5122

5223
## License
5324

5425
Copyright (c) 2013 - 2026, Thomas Aglassinger
5526
All rights reserved.
5627

57-
Distributed under the BSD license, see [LICENSE.txt](LICENSE.txt) for more
58-
information.
28+
Distributed under the BSD license, see [LICENSE.txt](LICENSE.txt) for more information.

‎ebcdic/README.md‎

Lines changed: 12 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
# ebcdic
22

3-
`ebcdic` is a Python package adding additional EBCDIC codecs for data exchange with legacy systems. It supports Python 3.9 and later.
3+
`ebcdic` is a Python package adding additional EBCDIC codecs for data exchange with legacy systems.
44

5-
[EBCDIC](https://en.wikipedia.org/wiki/EBCDIC) is short for "E"xtended Binary Coded Decimal Interchange Code" and is a family of character encodings that is mainly used on mainframe computers. There is no real point in using it unless you have to exchange data with legacy systems that still only support EBCDIC as character encoding.
5+
[EBCDIC](https://en.wikipedia.org/wiki/EBCDIC) is short for "Extended Binary Coded Decimal Interchange Code" and is a family of character encodings that is mainly used on mainframe computers. There is no real point in using it unless you have to exchange data with legacy systems.
6+
7+
This package requires Python 3.9 or later.
68

79
For compatibility with Python 2.7 to 3.3, use [version 1.1.1](https://pypi.org/project/ebcdic/1.1.1/).
810

@@ -12,7 +14,9 @@ For compatibility with Python 2.6 to 3.2, use [version 1.0.0](https://pypi.org/p
1214

1315
The `ebcdic` package is available from <https://pypi.python.org/pypi/ebcdic> and can be installed using pip:
1416

15-
pip install ebcdic
17+
```console
18+
pip install ebcdic
19+
```
1620

1721
## Example usage
1822

@@ -87,97 +91,11 @@ According to a [comprehensive list of code pages](https://www.aivosto.com/articl
8791

8892
## Source code
8993

90-
These codecs have been generated using CodecMapper, available from <https://github.com/roskakori/CodecMapper>. Read the README to build the ebcdic package from source.
94+
These codecs have been generated using CodecMapper, available from <https://github.com/roskakori/CodecMapper>. Read the [CONTRIBUTING.md](https://github.com/roskakori/CodecMapper/blob/master/CONTRIBUTING.md) to build the ebcdic package from the source and learn how to add more codecs.
9195

92-
To add another 8-bit EBCDIC codec, extend the ant target `ebcdic` in `build.xml` using a line like:
93-
94-
```xml
95-
<arg value="cpXXX" />
96-
```
96+
## License
9797

98-
Replace `XXX` by the number of the 8-bit code page you want to include.
99-
100-
Then run:
101-
102-
```bash
103-
ant test
104-
```
98+
Copyright (c) 2013 - 2026, Thomas Aglassinger
99+
All rights reserved.
105100

106-
to build and test the distribution.
107-
108-
## Changes
109-
110-
Version 2.0.0, 2026-02-23
111-
112-
This is a pure technical release that does not change the functionality of the package.
113-
114-
It ensures that the package builds with a modern Python toolchain and continuous integration systems. For details, see [#8](https://github.com/roskakori/CodecMapper/issues/8), contributed by [Branch Vincent](https://github.com/branchv)). In addition, it cleans up some source files missing from the distribution (see [#17](https://github.com/roskakori/CodecMapper/issues/17)) and several minor issues in the documentation.
115-
116-
Because of that, support for Python 2 and Python 3.8 or older had to be dropped. If you are stuck with such a version, use [ebcdic 1.1.1](https://pypi.org/project/ebcdic/1.1.1/), which currently has the same functionality.
117-
118-
Version 1.1.1, 2019-08-09
119-
120-
- Moved license information from README to LICENSE (#5). This required
121-
the distribution to change from sdist to wheel because apparently it
122-
is a major challenge to include a text file in a platform
123-
independent way (#11).
124-
125-
Sadly this breaks compatibility with Python 2.6, 3.1, 3.2 and 3.3.
126-
If you still need `ebcdic` with one of these Python versions, use
127-
`ebcdic-1.0.0`.
128-
129-
This took several attempts and intermediate releases that where
130-
broken in different ways on different platforms. To prevent people
131-
from accidentally installing one of these broken releases they have
132-
been removed from PyPI. If you still want to take a look at them,
133-
use the [respective
134-
tags](https://github.com/roskakori/CodecMapper/releases).
135-
136-
Version 1.0.0, 2019-06-06
137-
138-
- Changed development status to "Production/Stable".
139-
- Added international code pages cp500ms and cp1148ms which are the
140-
Microsoft interpretations of the respective IBM code pages. The only
141-
difference is that 0x1f is mapped to 0x85 ("next line") instead of
142-
0x0a ("new line"). Note that codecs.cp500 included with the Python
143-
standard library also uses the Microsoft interpretation (#4).
144-
- Added Arabian bilingual code page 420.
145-
- Added Baltic code page 1112.
146-
- Added Cyrillic code page 1025.
147-
- Added Eastern Europe code page 870.
148-
- Added Estonian code pages 1122 and 1157.
149-
- Added Greek code page 875.
150-
- Added Farsi Bilingual code page 1097.
151-
- Added Hebrew code page 424 and 803.
152-
- Added Korean code page 833.
153-
- Added Meahreb/French code page 425.
154-
- Added Japanese (Katakana) code page 290.
155-
- Added Thailand code page 838.
156-
- Added Turkish code page 322.
157-
- Added Ukraine code page 1123.
158-
- Added Python 3.5 to 3.8 as supported versions.
159-
- Improved PEP8 conformance of generated codecs.
160-
161-
Version 0.7, 2014-11-17
162-
163-
- Clarified which codecs are already part of the standard library and
164-
that these codecs overrule the `ebcdic` package. Also added a
165-
function `ebcdic.ignored_codec_names()` that returns the name of the
166-
EBCDIC codecs provided by other means. To obtain access to `ebcdic`
167-
codecs overruled by the standard library, use `ebcdic.lookup()`.
168-
- Cleaned up (PEP8, \_\_all\_\_, typos, ...).
169-
170-
Version 0.6, 2014-11-15
171-
172-
- Added support for Python 2.6+ and 3.1+ (#1).
173-
- Included a modified version of `gencodec.py` that still builds maps
174-
instead of tables so the generated codecs work with Python versions
175-
earlier than 3.3. It also does a <span class="title-ref">from
176-
\_\_future\_\_ import unicode_literals</span> so the codecs even
177-
work with Python 2.6+ using the same source code. As a side effect,
178-
this simplifies building the codecs because it removes the the need
179-
for a local copy of the cpython source code.
180-
181-
Version 0.5, 2014-11-13
182-
183-
- Initial public release
101+
Distributed under the BSD license, see [LICENSE.txt](https://github.com/roskakori/CodecMapper/blob/master/LICENSE.txt) for more information.

0 commit comments

Comments
 (0)