Skip to content

Commit 4dd5129

Browse files
author
Hugo Osvaldo Barrera
committed
Redo the documentation
- Set up sphinx again from scratch to kill of lots of legacy, bogus code. - Reorganise all docs, and make sure everything is accessible via the index (lots of things were unreadable). - DRY. A lot!
1 parent 0d71f97 commit 4dd5129

File tree

21 files changed

+649
-979
lines changed

21 files changed

+649
-979
lines changed

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
barcode/__pycache*
1313
build/*
1414
dist/*
15-
docs/build/*
15+
docs/_build
1616
MANIFEST
1717
barcode/version.py
1818
tests/index.html

‎README.rst‎

Lines changed: 13 additions & 259 deletions
Original file line numberDiff line numberDiff line change
@@ -25,269 +25,23 @@ python-barcode
2525
:target: https://github.com/WhyNotHugo/python-barcode/blob/master/LICENCE
2626
:alt: licence
2727

28-
This library provides a simple way to create barcodes using only the
29-
Python standard lib. The barcodes are created as SVG objects.
28+
**python-barcode** provides a simple way to create barcodes in Python.
3029

31-
.. image:: https://github.com/WhyNotHugo/python-barcode/blob/v0.13.1/example-ean13.png
32-
:target: https://github.com/WhyNotHugo/python-barcode
33-
:alt: python-barcode
34-
35-
Full documentation is published at http://python-barcode.rtfd.io/
36-
37-
Please report any bugs at https://github.com/WhyNotHugo/python-barcode/issues
38-
39-
Features
40-
--------
41-
42-
- Works on Python 3.6 to 3.9
43-
- No visualiser (just use your browser)
44-
- Generate barcodes as SVG files.
45-
- Generate barcodes as images (png, jpeg, etc). Requires Pillow.
46-
47-
Installation
48-
------------
49-
50-
The best way is to use pip: ``pip install python-barcode``. Don't forget to add
51-
this to our app's dependencies.
52-
53-
If you'll be exporting to images (eg: not just SVG), you'll need additional
54-
optional dependencies, so run: ``pip install "python-barcode[images]"`` (keep the
55-
quotes, most shells don't play nice with square brackets).
56-
57-
Provided Barcodes
58-
-----------------
59-
60-
* EAN-8
61-
* EAN-13
62-
* EAN-14
63-
* UPC-A
64-
* JAN
65-
* ISBN-10
66-
* ISBN-13
67-
* ISSN
68-
* Code 39
69-
* Code 128
70-
* PZN
71-
72-
PRs for other code formats are welcome!
73-
74-
Usage
75-
-----
76-
77-
Programmatic::
78-
79-
from barcode import EAN13
80-
from barcode.writer import ImageWriter
81-
82-
# print to a file-like object:
83-
rv = BytesIO()
84-
EAN13(str(100000902922), writer=ImageWriter()).write(rv)
85-
86-
# or sure, to an actual file:
87-
with open('somefile.jpeg', 'wb') as f:
88-
EAN13('100000011111', writer=ImageWriter()).write(f)
89-
90-
Interactive::
91-
92-
>>> import barcode
93-
>>> barcode.PROVIDED_BARCODES
94-
['code39', 'code128', 'ean', 'ean13', 'ean8', 'gs1', 'gtin',
95-
'isbn', 'isbn10', 'isbn13', 'issn', 'jan', 'pzn', 'upc', 'upca']
96-
>>> EAN = barcode.get_barcode_class('ean13')
97-
>>> EAN
98-
<class 'barcode.ean.EuropeanArticleNumber13'>
99-
>>> ean = EAN('5901234123457')
100-
>>> ean
101-
<barcode.ean.EuropeanArticleNumber13 object at 0x00BE98F0>
102-
>>> fullname = ean.save('ean13_barcode')
103-
>>> fullname
104-
'ean13_barcode.svg'
105-
# Example with PNG
106-
>>> from barcode.writer import ImageWriter
107-
>>> ean = EAN('5901234123457', writer=ImageWriter())
108-
>>> fullname = ean.save('ean13_barcode')
109-
'ean13_barcode.png'
110-
# New in v0.4.2
111-
>>> from io import BytesIO
112-
>>> fp = BytesIO()
113-
>>> ean.write(fp)
114-
# or
115-
>>> f = open('/my/new/file', 'wb')
116-
>>> ean.write(f) # Pillow (ImageWriter) produces RAW format here
117-
>>> from barcode import generate
118-
>>> name = generate('EAN13', '5901234123457', output='barcode_svg')
119-
>>> name
120-
'barcode_svg.svg'
121-
# with file like object
122-
>>> fp = BytesIO()
123-
>>> generate('EAN13', '5901234123457', writer=ImageWriter(), output=fp)
124-
>>>
125-
126-
Now open ean13_barcode.[svg|png] in a graphic app or simply in your browser
127-
and see the created barcode. That's it.
128-
129-
Commandline::
130-
131-
`$ python-barcode create "123456789000" outfile -b ean --text "text to appear under barcode" `
132-
New barcode saved as outfile.svg.
133-
134-
# The following will not work if Pillow is not installed (Pillow is required for exporting to images instead of SVG).
135-
$ python-barcode create -t png "My Text" outfile
136-
New barcode saved as outfile.png.
137-
138-
Try `python-barcode -h` for help.
139-
140-
Changelog
141-
---------
142-
143-
v0.13.1
144-
~~~~~~~
145-
146-
* Fix a crash when using the ``generate`` shortcut function.
147-
148-
v0.13.0
149-
~~~~~~~
150-
151-
* Added support for transparent backgrounds. This is done by setting the ``mode`` option
152-
for a writer to ``RGBA``.
30+
There are no external dependencies when generating SVG files.
31+
Pillow is required for generating images (e.g.: PNGs).
15332

154-
v0.12.0
155-
~~~~~~~
33+
Support Python 3.6 to 3.9.
15634

157-
* Removed ``writer_options`` from ``barcode.get``. This parameter was not used.
158-
* Add a ``with_doctype`` flag to ``SVGWriter``. Set this to false to avoid including a
159-
``DOCTYPE`` in the resulting SVG.
160-
* Add support for ``Pillow>=8.0.0``.
161-
162-
v0.11.0
163-
~~~~~~~
164-
165-
* Added basic support for multiline text.
166-
* Dropped lots of older compat-only code and other cleanups.
167-
* Fixed a bug in the API when combining certain barcodes and writers.
168-
* Published documentation again and updated all project references.
169-
* Fix python_barcode.get mixups between `options` as `writer_options`.
170-
Previously, some writer/barcode combinations worked fine, while others
171-
failed. Now all work consistently.
172-
* The cli tool has been fixed and should now work as expected again.
173-
174-
v0.10.0
175-
~~~~~~~
176-
177-
* Added support for GS1-128.
178-
179-
v0.9.1
180-
~~~~~~
181-
182-
* Officially support Python 3.7
183-
* Refer to Pillow in the docs, rather than PIL.
184-
185-
v0.9.0
186-
~~~~~~
187-
188-
* Removed buggy ``Barcode.raw`` attribute.
189-
* Various CLI errors ironed out.
190-
* Make the default value for ``writer_options``` consistent across writers.
191-
192-
v0.8.3
193-
~~~~~~
194-
195-
* Fix pushing of releases to GitHub.
196-
197-
v0.8.2
198-
~~~~~~
199-
200-
* Fix crashes when attempting to use the CLI app.
201-
* Properly include version numbers in SVG comments.
202-
203-
v0.8.1
204-
~~~~~~
205-
* Improve README rendering, and point to this fork's location (the outdated
206-
README on PyPI was causing some confusion).
207-
208-
v0.8.0
209-
~~~~~~
210-
* First release under the name ``python-barcode``.
211-
212-
Previous Changelog
213-
------------------
214-
215-
This project is a fork of pyBarcode, which, apparently, is no longer
216-
maintained. v0.8.0 is our first release, and is the latest ``master`` from that
217-
parent project.
218-
219-
v0.8
220-
~~~~
221-
* Code 128 added.
222-
* Data for charsets and bars moved to subpackage barcode.charsets.
223-
* Merged in some improvements.
224-
225-
v0.7
226-
~~~~
227-
* Fixed some issues with fontsize and fontalignment.
228-
* Added Python 3 support. It's not well tested yet, but the tests run without
229-
errors with Python 3.3. Commandline script added.
230-
231-
v0.6
232-
~~~~
233-
* Changed save and write methods to take the options as a dict not as keyword
234-
arguments (fix this in your code). Added option to left align the text under
235-
the barcode. Fixed bug with EAN13 generation.
236-
237-
v0.5.0
238-
~~~~~~
239-
* Added new generate function to do all generation in one step.
240-
* Moved writer from a subpackage to a module (this breaks some existing code).
241-
UPC is now rendered as real UPC, not as EAN13 with the leading "0".
242-
243-
v0.4.3
244-
~~~~~~
245-
* Fixed bug in new write method (related to PIL) and updated docs.
246-
247-
v0.4.2
248-
~~~~~~
249-
* Added write method to support file like objects as target.
250-
251-
v0.4.1
252-
~~~~~~
253-
* Bugfix release. Removed redundancy in input validation.
254-
* EAN8 was broken. It now works as expected.
255-
256-
v0.4
257-
~~~~
258-
* Removed \*\*options from writers __init__ method. These options never had
259-
effect. They were always overwritten by default_options.
260-
* New config option available: text_distance (the distance between barcode and
261-
text).
262-
263-
v0.4b2
264-
~~~~~~
265-
* Basic documentation included. The barcode object now has a new attribute
266-
called `raw` to have the rendered output without saving to disk.
267-
268-
v0.4b1
269-
~~~~~~
270-
* Support for rendering barcodes as images is implemented. PIL is required to
271-
use it.
272-
273-
v0.3
274-
~~~~
275-
* Compression for SVG output now works.
35+
.. image:: example-ean13.png
36+
:target: https://github.com/WhyNotHugo/python-barcode
37+
:alt: python-barcode
27638

277-
v0.3b1
278-
~~~~~~
279-
* Writer API has changed for simple adding new (own) writers.
280-
* SVG output is now generated with xml.dom module instead of stringformatting
281-
(makes it more robust).
39+
Documentation
40+
-------------
28241

283-
v0.2.1
284-
~~~~~~
285-
* API of render changed. Now render takes keyword arguments instead of a dict.
42+
Full documentation is published at http://python-barcode.rtfd.io/
28643

287-
v0.2
288-
~~~~
289-
* More tests added.
44+
Licence
45+
-------
29046

291-
v0.1
292-
~~~~
293-
* First release.
47+
python-barcode is licensed under the MIT licence. See LICENCE for details.

‎barcode/codex.py‎

Lines changed: 11 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -30,21 +30,18 @@ def check_code(code, name, allowed):
3030

3131

3232
class Code39(Barcode):
33-
r"""Initializes a new Code39 instance.
34-
35-
:parameters:
36-
code : String
37-
Code 39 string without \* and checksum (added automatically if
38-
`add_checksum` is True).
39-
writer : barcode.writer Instance
40-
The writer to render the barcode (default: SVGWriter).
41-
add_checksum : Boolean
42-
Add the checksum to code or not (default: True).
43-
"""
33+
"""A Code39 barcode implementation"""
4434

4535
name = "Code 39"
4636

47-
def __init__(self, code, writer=None, add_checksum=True):
37+
def __init__(self, code: str, writer=None, add_checksum: bool = True):
38+
r"""
39+
:param code: Code 39 string without \* and without checksum.
40+
:param writer: A ``barcode.writer`` instance used to render the barcode
41+
(default: SVGWriter).
42+
:param add_checksum: Add the checksum to code or not
43+
"""
44+
4845
self.code = code.upper()
4946
if add_checksum:
5047
self.code += self.calculate_checksum()
@@ -54,7 +51,8 @@ def __init__(self, code, writer=None, add_checksum=True):
5451
def __str__(self):
5552
return self.code
5653

57-
def get_fullcode(self):
54+
def get_fullcode(self) -> str:
55+
""":returns: The full code as it will be encoded."""
5856
return self.code
5957

6058
def calculate_checksum(self):

0 commit comments

Comments
 (0)