Skip to content

Commit b148a4b

Browse files
ddaleddale
committed
added support for setting docstrings when instantiating units and
constants. Allows users to do something like "pq.au?" in ipython, although "help(pq.au)" seems to ignore the instance's __doc__ and goes straight to the class itself. This support should also enable the docstrings for units and constants to be integrated with the packages documentation using sphinx
1 parent 48dfcdf commit b148a4b

File tree

17 files changed

+101
-83
lines changed

17 files changed

+101
-83
lines changed

‎quantities/constants/astronomy.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,9 @@
1111
au = astronomical_unit = UnitConstant(
1212
'astronomical_unit',
1313
UncertainQuantity(149597870691, 'm', 30),
14-
symbol='au'
15-
) # http://en.wikipedia.org/wiki/Astronomical_unit
14+
symbol='au',
15+
doc='http://en.wikipedia.org/wiki/Astronomical_unit'
16+
)
1617
G = Newtonian_constant_of_gravitation = UnitConstant(
1718
'Newtonian_constant_of_gravitation',
1819
_cd('Newtonian constant of gravitation'),

‎quantities/constants/astrophysics.py‎

Lines changed: 0 additions & 21 deletions
This file was deleted.

‎quantities/unitquantity.py‎

Lines changed: 7 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ class UnitQuantity(Quantity):
3232

3333
def __new__(
3434
cls, name, definition=None, symbol=None, u_symbol=None,
35-
aliases=[], note=None
35+
aliases=[], doc=None
3636
):
3737
try:
3838
assert isinstance(name, str)
@@ -52,7 +52,8 @@ def __new__(
5252
ret._name = name
5353
ret._symbol = symbol
5454
ret._u_symbol = u_symbol
55-
ret._note = note
55+
if doc is not None:
56+
ret.__doc__ = doc
5657

5758
if definition is not None:
5859
if not isinstance(definition, Quantity):
@@ -70,7 +71,7 @@ def __new__(
7071

7172
def __init__(
7273
self, name, definition=None, symbol=None, u_symbol=None,
73-
aliases=[], note=None
74+
aliases=[], doc=None
7475
):
7576
unit_registry[name] = self
7677
if symbol:
@@ -100,10 +101,6 @@ def format_order(self):
100101
def name(self):
101102
return self._name
102103

103-
@property
104-
def note(self):
105-
return self._note
106-
107104
@property
108105
def definition(self):
109106
if self._definition is None:
@@ -163,8 +160,6 @@ def __str__(self):
163160
else:
164161
s = '1 %s'%self.name
165162

166-
# if self.note:
167-
# return s+'\nnote: %s'%self.note
168163
return s
169164

170165
@with_doc(Quantity.__add__, use_header=False)
@@ -248,10 +243,10 @@ class IrreducibleUnit(UnitQuantity):
248243

249244
def __init__(
250245
self, name, definition=None, symbol=None, u_symbol=None,
251-
aliases=[], note=None
246+
aliases=[], doc=None
252247
):
253248
super(IrreducibleUnit, self).__init__(
254-
name, definition, symbol, u_symbol, aliases, note
249+
name, definition, symbol, u_symbol, aliases, doc
255250
)
256251
cls = type(self)
257252
if cls._default_unit is None:
@@ -374,7 +369,7 @@ class UnitConstant(UnitQuantity):
374369

375370
def __init__(
376371
self, name, definition=None, symbol=None, u_symbol=None,
377-
aliases=[], note=None
372+
aliases=[], doc=None
378373
):
379374
# we dont want to register constants in the unit registry
380375
return

‎quantities/units/acceleration.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@
1212
'standard_gravity',
1313
9.806650*m/s**2,
1414
symbol='g',
15-
u_symbol='g₀'
16-
) # exact
15+
u_symbol='g₀',
16+
doc='exact'
17+
)
1718

1819
del m, s, UnitQuantity

‎quantities/units/area.py‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
5.067075e-10*m**2,
2323
symbol='cmil',
2424
aliases=['circular_mils'],
25-
note='conversions approximate, area of a circle with diameter=1 mil'
25+
doc='conversions approximate, area of a circle with diameter=1 mil'
2626
)
2727
D = darcy = UnitQuantity(
2828
'darcy',
@@ -43,8 +43,9 @@
4343
acre = international_acre = UnitQuantity(
4444
'acre',
4545
4046.8564224*m**2,
46-
aliases=['acres', 'international_acre', 'international_acres']
47-
) # exact: http://en.wikipedia.org/wiki/Acre
46+
aliases=['acres', 'international_acre', 'international_acres'],
47+
doc="exact. http://en.wikipedia.org/wiki/Acre"
48+
)
4849
US_survey_acre = UnitQuantity(
4950
'US_survey_acre',
5051
160*rod**2,

‎quantities/units/electromagnetism.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@
142142
'elementary_charge',
143143
1.602176487e-19*C,
144144
symbol='e',
145-
note='relative uncertainty = 6.64e-8'
145+
doc='relative uncertainty = 6.64e-8'
146146
)
147147
chemical_faraday = UnitQuantity(
148148
'chemical_faraday',

‎quantities/units/energy.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@
100100
4.35974394e-18*J,
101101
symbol='E_h',
102102
aliases=['hartrees', 'hartree_energy', 'Hartree_energy'],
103-
note='relative uncertainty = 2.1e-6'
103+
doc='relative uncertainty = 2.1e-6'
104104
)
105105

106106
del UnitQuantity, dyne, N, cm, m, s, h

‎quantities/units/heat.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
RSI = UnitQuantity(
1414
'RSI',
1515
K*m**2/W,
16-
note='R-value in SI'
16+
doc='R-value in SI'
1717
)
1818

1919
clo = clos = UnitQuantity(
@@ -25,7 +25,7 @@
2525
R_value = UnitQuantity(
2626
'R_value',
2727
ft**2*degF*h/BTU,
28-
note='American customary units'
28+
doc='American customary units'
2929
)
3030

3131

‎quantities/units/length.py‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@
9797
3.08568025e16*m,
9898
symbol='pc',
9999
aliases=['parsecs'],
100-
note='approximate'
100+
doc='approximate'
101101
)
102102
ly = light_year = UnitLength(
103103
'light_year',
@@ -110,7 +110,15 @@
110110
149597870691*m,
111111
symbol='au',
112112
aliases=['astronomical_units'],
113-
note='uncertainty ± 30 m'
113+
doc='''
114+
An astronomical unit (abbreviated as AU, au, a.u., or sometimes ua) is a
115+
unit of length roughly equal to the mean distance between the Earth and
116+
the Sun. It is approximately 150 million kilometres (93 million miles).
117+
118+
uncertainty ± 30 m
119+
120+
http://en.wikipedia.org/wiki/Astronomical_unit
121+
'''
114122
)
115123

116124
nmi = nautical_mile = UnitLength(

‎quantities/units/mass.py‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -27,14 +27,16 @@
2727
'ounce',
2828
28.349523125*g,
2929
symbol='oz',
30-
aliases=['ounces','avoirdupois_ounce', 'avoirdupois_ounces']
31-
) # exact
30+
aliases=['ounces','avoirdupois_ounce', 'avoirdupois_ounces'],
31+
doc='exact'
32+
)
3233
lb = pound = avoirdupois_pound = UnitMass(
3334
'pound',
3435
0.45359237*kg,
3536
symbol='lb',
36-
aliases=['pounds', 'avoirdupois_pound', 'avoirdupois_pounds']
37-
) # exact
37+
aliases=['pounds', 'avoirdupois_pound', 'avoirdupois_pounds'],
38+
doc='exact'
39+
)
3840

3941
carat = UnitMass(
4042
'carat',
@@ -99,7 +101,7 @@
99101
1.660538782e-27*kg,
100102
symbol='u',
101103
aliases=['amu'],
102-
note='relative uncertainty = 5e-8'
104+
doc='relative uncertainty = 5e-8'
103105
)
104106
scruple = UnitMass(
105107
'scruple',

0 commit comments

Comments
 (0)