Skip to content

Commit 6995515

Browse files
domdfcodingdomdfcoding
committed
Updated docs.
1 parent 2d35918 commit 6995515

File tree

3 files changed

+162
-93
lines changed

3 files changed

+162
-93
lines changed

‎doc-source/api/pagesizes/sizes.rst‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
=========================================
44

55
.. automodule:: domdf_python_tools.pagesizes.sizes
6+
:no-members:
7+
:autosummary-members:
8+
:autosummary-undoc-members:
9+
:autosummary-no-titles:
610
:undoc-members:
7-
:special-members:
8-
:private-members:

‎domdf_python_tools/pagesizes/sizes.py‎

Lines changed: 50 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@
77
.. TODO:: finish the list of the page sizes
88
99
.. |iso216| replace:: `ISO 216 <https://en.wikipedia.org/wiki/ISO_216>`__
10+
11+
Each pagesize is an instance of :class:`domdf_python_tools.pagesizes.PageSize`.
12+
The following sizes are available:
1013
"""
1114
#
1215
# Copyright © 2020 Dominic Davis-Foster <dominic@davis-foster.co.uk>
@@ -224,54 +227,54 @@
224227
TABLOID = ELEVENSEVENTEEN = Size_inch(11, 17).to_pt()
225228

226229
# From https://en.wikipedia.org/wiki/Paper_size
227-
JUNIOR_LEGAL = Size_inch(5, 8).to_pt()
228-
HALF_LETTER = Size_inch(5.5, 8).to_pt()
229-
GOV_LETTER = Size_inch(8, 10.5).to_pt()
230-
GOV_LEGAL = Size_inch(8.5, 13).to_pt()
231-
LEDGER = Size_inch(17, 11).to_pt()
232-
EMPEROR = Size_inch(48, 72).to_pt()
233-
QUAD_ROYAL = Size_inch(40, 50).to_pt()
234-
QUAD_DEMY = Size_inch(35, 40).to_pt()
235-
ANTIQUARIAN = Size_inch(31, 53).to_pt()
236-
GRAND_EAGLE = Size_inch(28.75, 42).to_pt()
237-
DOUBLE_ELEPHANT = Size_inch(26.75, 40).to_pt()
238-
ATLAS = Size_inch(26, 34).to_pt()
239-
DOUBLE_ROYAL = Size_inch(25, 40).to_pt()
240-
COLOMBIER = Size_inch(23.5, 34.5).to_pt()
241-
DOUBLE_DEMY_US = Size_inch(22.5, 35.5).to_pt()
242-
DOUBLE_DEMY = DOUBLE_DEMY_UK = Size_inch(22.5, 35).to_pt()
243-
IMPERIAL = Size_inch(22, 30).to_pt()
244-
DOUBLE_LARGE_POST = Size_inch(21, 33).to_pt()
245-
ELEPHANT = Size_inch(23, 28).to_pt()
246-
PRINCESS = Size_inch(22.5, 28).to_pt()
247-
CARTRIDGE = Size_inch(21, 26).to_pt()
248-
ROYAL = Size_inch(20, 25).to_pt()
249-
SHEET = HALF_POST = Size_inch(19.5, 23.5).to_pt()
250-
DOUBLE_POST = Size_inch(19, 30.5).to_pt()
251-
SUPER_ROYAL = Size_inch(19, 27).to_pt()
252-
BROADSHEET = Size_inch(18, 24).to_pt()
253-
MEDIUM_US = Size_inch(17.5, 23).to_pt()
254-
MEDIUM_UK = Size_inch(18, 23).to_pt()
255-
DEMY = Size_inch(17.5, 22.5).to_pt()
256-
COPY_DRAUGHT = Size_inch(16, 20).to_pt()
257-
LARGE_POST_US = Size_inch(15.5, 20).to_pt()
258-
LARGE_POST_UK = Size_inch(16.5, 21).to_pt()
259-
POST_US = Size_inch(15.5, 19.35).to_pt()
260-
POST_UK = Size_inch(15.5, 19.5).to_pt()
261-
CROWN = Size_inch(15, 20).to_pt()
262-
PINCHED_POST = Size_inch(14.75, 18.5).to_pt()
263-
FOOLSCAP_US = Size_inch(13.5, 17).to_pt()
264-
FOOLSCAP_UK = Size_inch(13, 18).to_pt()
265-
SMALL_FOOLSCAP = Size_inch(13.35, 16.5).to_pt()
266-
BRIEF = Size_inch(13.5, 16).to_pt()
267-
POTT = Size_inch(12.5, 15).to_pt()
268-
QUARTO_US = Size_inch(9, 11).to_pt()
269-
EXECUTIVE = MONARCH = Size_inch(7.35, 10.5).to_pt()
270-
FOLIO = FOOLSCAP_FOLIO = Size_inch(8, 13).to_pt()
271-
QUARTO = QUARTO_UK = Size_inch(8, 10).to_pt()
230+
JUNIOR_LEGAL = Size_inch(5, 8).to_pt() #: Junior Legal
231+
HALF_LETTER = Size_inch(5.5, 8).to_pt() #: Half Letter
232+
GOV_LETTER = Size_inch(8, 10.5).to_pt() #: Government Letter
233+
GOV_LEGAL = Size_inch(8.5, 13).to_pt() #: Government Legal
234+
LEDGER = Size_inch(17, 11).to_pt() #: Ledger
235+
EMPEROR = Size_inch(48, 72).to_pt() #: Emperor
236+
QUAD_ROYAL = Size_inch(40, 50).to_pt() #: Quad Royal
237+
QUAD_DEMY = Size_inch(35, 40).to_pt() #:
238+
ANTIQUARIAN = Size_inch(31, 53).to_pt() #:
239+
GRAND_EAGLE = Size_inch(28.75, 42).to_pt() #:
240+
DOUBLE_ELEPHANT = Size_inch(26.75, 40).to_pt() #:
241+
ATLAS = Size_inch(26, 34).to_pt() #:
242+
DOUBLE_ROYAL = Size_inch(25, 40).to_pt() #:
243+
COLOMBIER = Size_inch(23.5, 34.5).to_pt() #:
244+
DOUBLE_DEMY_US = Size_inch(22.5, 35.5).to_pt() #:
245+
DOUBLE_DEMY = DOUBLE_DEMY_UK = Size_inch(22.5, 35).to_pt() #:
246+
IMPERIAL = Size_inch(22, 30).to_pt() #:
247+
DOUBLE_LARGE_POST = Size_inch(21, 33).to_pt() #:
248+
ELEPHANT = Size_inch(23, 28).to_pt() #:
249+
PRINCESS = Size_inch(22.5, 28).to_pt() #:
250+
CARTRIDGE = Size_inch(21, 26).to_pt() #:
251+
ROYAL = Size_inch(20, 25).to_pt() #:
252+
SHEET = HALF_POST = Size_inch(19.5, 23.5).to_pt() #:
253+
DOUBLE_POST = Size_inch(19, 30.5).to_pt() #:
254+
SUPER_ROYAL = Size_inch(19, 27).to_pt() #:
255+
BROADSHEET = Size_inch(18, 24).to_pt() #:
256+
MEDIUM_US = Size_inch(17.5, 23).to_pt() #:
257+
MEDIUM_UK = Size_inch(18, 23).to_pt() #:
258+
DEMY = Size_inch(17.5, 22.5).to_pt() #:
259+
COPY_DRAUGHT = Size_inch(16, 20).to_pt() #:
260+
LARGE_POST_US = Size_inch(15.5, 20).to_pt() #:
261+
LARGE_POST_UK = Size_inch(16.5, 21).to_pt() #:
262+
POST_US = Size_inch(15.5, 19.35).to_pt() #:
263+
POST_UK = Size_inch(15.5, 19.5).to_pt() #:
264+
CROWN = Size_inch(15, 20).to_pt() #:
265+
PINCHED_POST = Size_inch(14.75, 18.5).to_pt() #:
266+
FOOLSCAP_US = Size_inch(13.5, 17).to_pt() #:
267+
FOOLSCAP_UK = Size_inch(13, 18).to_pt() #:
268+
SMALL_FOOLSCAP = Size_inch(13.35, 16.5).to_pt() #:
269+
BRIEF = Size_inch(13.5, 16).to_pt() #:
270+
POTT = Size_inch(12.5, 15).to_pt() #:
271+
QUARTO_US = Size_inch(9, 11).to_pt() #:
272+
EXECUTIVE = MONARCH = Size_inch(7.35, 10.5).to_pt() #:
273+
FOLIO = FOOLSCAP_FOLIO = Size_inch(8, 13).to_pt() #:
274+
QUARTO = QUARTO_UK = Size_inch(8, 10).to_pt() #:
272275
# IMPERIAL = Size_inch(7*inch, 9*inch).to_pt() there are two of these?
273-
KINGS = Size_inch(6.5, 8).to_pt()
274-
DUKES = Size_inch(5.5, 7).to_pt()
276+
KINGS = Size_inch(6.5, 8).to_pt() #:
277+
DUKES = Size_inch(5.5, 7).to_pt() #:
275278

276279
# https://en.wikipedia.org/wiki/ISO/IEC_7810
277280
ID_1 = Size_mm(85.60, 53.98).to_pt() #: Most banking cards and ID cards

‎domdf_python_tools/pagesizes/units.py‎

Lines changed: 108 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,9 @@
3535
from decimal import ROUND_HALF_UP, Decimal
3636
from typing import Union
3737

38+
# this package
39+
from domdf_python_tools.doctools import prettify_docstrings
40+
3841
__all__ = [
3942
"pt",
4043
"inch",
@@ -44,13 +47,20 @@
4447
"pc",
4548
"pica",
4649
"Unit",
50+
"Unitpt",
51+
"UnitInch",
52+
"Unitcm",
53+
"Unitmm",
54+
"Unitum",
55+
"Unitpc",
4756
]
4857

4958

5059
def _rounders(val_to_round: Union[str, int, float, Decimal], round_format: str) -> Decimal:
5160
return Decimal(Decimal(val_to_round).quantize(Decimal(str(round_format)), rounding=ROUND_HALF_UP))
5261

5362

63+
@prettify_docstrings
5464
class Unit(float):
5565
"""
5666
Represents a unit, such as a point.
@@ -61,78 +71,96 @@ class Unit(float):
6171
6272
Units can be added to each other:
6373
64-
>>> (3*mm) + (7*mm)
65-
<Unit '10.000 mm': 28.346pt>
74+
.. code-block:: python
75+
76+
>>> (3*mm) + (7*mm)
77+
<Unit '10.000 mm': 28.346pt>
6678
6779
When adding different :class:`~domdf_python_tools.pagesizes.units.Unit` objects,
6880
the result has the type of the former unit:
6981
70-
>>> (2.54*cm) + inch
71-
<Unit '5.080 cm': 144.000pt>
72-
>>> inch + (2.54*cm)
73-
<Unit '2.000 in': 144.000pt>
82+
.. code-block:: python
83+
84+
>>> (2.54*cm) + inch
85+
<Unit '5.080 cm': 144.000pt>
86+
>>> inch + (2.54*cm)
87+
<Unit '2.000 in': 144.000pt>
7488
7589
:class:`~domdf_python_tools.pagesizes.units.Unit` objects can also be added to :class:`float` and :class:`int` objects:
7690
77-
>>> (3*cm) + 7
78-
<Unit '10.000 cm': 283.465pt>
79-
>>> 7 + (3*cm)
80-
<Unit '10.000 cm': 283.465pt>
91+
.. code-block:: python
92+
93+
>>> (3*cm) + 7
94+
<Unit '10.000 cm': 283.465pt>
95+
>>> 7 + (3*cm)
96+
<Unit '10.000 cm': 283.465pt>
8197
8298
8399
**Subtraction**
84100
85101
Subtraction works the same as addition:
86102
87-
>>> (17*mm) - (7*mm)
88-
<Unit '10.000 mm': 28.346pt>
89-
>>> (2.54*cm) - inch
90-
<Unit '-0.000 cm': -0.000pt>
91-
>>> inch - (2.54*cm)
92-
<Unit '0.000 in': 0.000pt>
93-
>>> (17*cm) - 7
94-
<Unit '10.000 cm': 283.465pt>
95-
>>> 17 - (7*cm)
96-
<Unit '10.000 cm': 283.465pt>
103+
.. code-block:: python
104+
105+
>>> (17*mm) - (7*mm)
106+
<Unit '10.000 mm': 28.346pt>
107+
>>> (2.54*cm) - inch
108+
<Unit '-0.000 cm': -0.000pt>
109+
>>> inch - (2.54*cm)
110+
<Unit '0.000 in': 0.000pt>
111+
>>> (17*cm) - 7
112+
<Unit '10.000 cm': 283.465pt>
113+
>>> 17 - (7*cm)
114+
<Unit '10.000 cm': 283.465pt>
97115
98116
99117
**Multiplcation**
100118
101119
:class:`~domdf_python_tools.pagesizes.units.Unit` objects can only be multipled by
102120
:class:`float` and :class:`int` objects:
103121
104-
>>> (3*mm) * 3
105-
<Unit '9.000 mm': 25.512pt>
106-
>>> 3 * (3*mm)
107-
<Unit '9.000 mm': 25.512pt>
108-
>>> 3.5 * (3*mm)
109-
<Unit '10.500 mm': 29.764pt>
122+
.. code-block:: python
123+
124+
>>> (3*mm) * 3
125+
<Unit '9.000 mm': 25.512pt>
126+
>>> 3 * (3*mm)
127+
<Unit '9.000 mm': 25.512pt>
128+
>>> 3.5 * (3*mm)
129+
<Unit '10.500 mm': 29.764pt>
110130
111131
Multiplication works either way round.
112132
113133
Multiplying by another :class:`~domdf_python_tools.pagesizes.units.Unit` results in a :exc:`TypeError`:
114134
115-
>>> inch * (7*cm)
116-
TypeError: unsupported operand type(s) for *: 'UnitInch' and 'Unitcm'
135+
.. code-block:: python
136+
137+
>>> inch * (7*cm)
138+
TypeError: unsupported operand type(s) for *: 'UnitInch' and 'Unitcm'
117139
118140
**Division**
119141
120142
:class:`~domdf_python_tools.pagesizes.units.Unit`s can only be divided by :class:`float` and :class:`int` objects:
121143
122-
>>> (3*mm) / 3
123-
<Unit '1.000 mm': 2.835pt>
124-
>>> (10*mm) / 2.5
125-
<Unit '4.000 mm': 11.339pt>
144+
.. code-block:: python
145+
146+
>>> (3*mm) / 3
147+
<Unit '1.000 mm': 2.835pt>
148+
>>> (10*mm) / 2.5
149+
<Unit '4.000 mm': 11.339pt>
126150
127151
Dividing by another unit results in a :exc:`TypeError`:
128152
129-
>>> inch / (7*cm)
130-
TypeError: unsupported operand type(s) for /: 'UnitInch' and 'Unitcm'
153+
.. code-block:: python
154+
155+
>>> inch / (7*cm)
156+
TypeError: unsupported operand type(s) for /: 'UnitInch' and 'Unitcm'
131157
132158
Likewise, trying to divide a:class:`float` and :class:`int` object by a unit results in a :exc:`TypeError`:
133159
134-
>>> 3 / (3*mm)
135-
TypeError: unsupported operand type(s) for /: 'int' and 'Unitmm'
160+
.. code-block:: python
161+
162+
>>> 3 / (3*mm)
163+
TypeError: unsupported operand type(s) for /: 'int' and 'Unitmm'
136164
137165
138166
**Powers**
@@ -145,8 +173,10 @@ class Unit(float):
145173
Modulo division of a :class:`~domdf_python_tools.pagesizes.units.Unit` by a
146174
:class:`float` or :class:`int` object is allowed:
147175
148-
>>> (3*mm) % 2.5
149-
<Unit '0.500 mm': 1.417pt>
176+
.. code-block:: python
177+
178+
>>> (3*mm) % 2.5
179+
<Unit '0.500 mm': 1.417pt>
150180
151181
Dividing by a unit, or modulo division of two units, is not officially supported.
152182
"""
@@ -235,50 +265,84 @@ def __rsub__(self, other: Union[float, "Unit"]) -> "Unit":
235265
return self.__class__(super().__rsub__(other))
236266

237267
def as_pt(self) -> "Unit":
268+
"""
269+
Returns the unit in point.
270+
"""
271+
238272
return Unit(float(_rounders(float(self) * self._in_pt, "0.000000")))
239273

240274
@classmethod
241275
def from_pt(cls, value: float) -> "Unit":
276+
"""
277+
Construct a :class:`~.Unit` object from a value in point.
278+
279+
:param value:
280+
"""
281+
242282
return cls(value / cls._in_pt)
243283

244284
def __call__(self, *args, **kwargs) -> "Unit":
245285
return self.__class__(*args, **kwargs)
246286

247287

248288
class Unitpt(Unit):
289+
"""
290+
Point
291+
"""
292+
249293
name = "pt"
250294
_in_pt = 1
251295

252296

253297
class UnitInch(Unit):
298+
"""
299+
Inch
300+
"""
301+
254302
name = "inch"
255303
_in_pt = 72.0
256304

257305

258306
class Unitcm(Unit):
307+
"""
308+
Centimetres
309+
"""
310+
259311
name = "cm"
260312
_in_pt = 28.3464566929
261313

262314

263315
class Unitmm(Unit):
316+
"""
317+
Millimetres
318+
"""
319+
264320
name = "mm"
265321
_in_pt = 2.83464566929
266322

267323

268324
class Unitum(Unit):
325+
"""
326+
Micrometres
327+
"""
328+
269329
name = "µm"
270330
_in_pt = 0.00283464566929
271331

272332

273333
class Unitpc(Unit):
334+
"""
335+
Pica
336+
"""
337+
274338
name = "pc"
275339
_in_pt = 12.0
276340

277341

278342
# Units
279-
pt = Unitpt(1)
280-
inch = UnitInch(1)
281-
cm = Unitcm(1)
282-
mm = Unitmm(1)
283-
um = Unitum(1)
284-
pc = pica = Unitpc(1)
343+
pt = Unitpt(1) #: Point
344+
inch = UnitInch(1) #: Inch
345+
cm = Unitcm(1) #: Centimetre
346+
mm = Unitmm(1) #: Millimetre
347+
um = Unitum(1) #: Micrometre
348+
pc = pica = Unitpc(1) #: Pica

0 commit comments

Comments
 (0)