Skip to content

Commit c3c0a4b

Browse files
KelSolaarKelSolaar
committed
Update docstrings in colour.io package.
1 parent ead456a commit c3c0a4b

21 files changed

+277
-200
lines changed

‎colour/io/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@ class io(ModuleAPI):
117117
"""Define a class acting like the *io* module."""
118118

119119
def __getattr__(self, attribute: str) -> Any:
120-
"""Return the value from the attribute with given name."""
120+
"""Return the value from the attribute with specified name."""
121121

122122
return super().__getattr__(attribute)
123123

‎colour/io/ctl.py‎

Lines changed: 43 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,8 @@ def ctl_render(
7373
**kwargs: Any,
7474
) -> subprocess.CompletedProcess: # pragma: no cover
7575
"""
76-
Call *ctlrender* on given input image using given *CTL* transforms.
76+
Invoke *ctlrender* on the specified input image using the specified
77+
*CTL* transforms.
7778
7879
Parameters
7980
----------
@@ -83,28 +84,34 @@ def ctl_render(
8384
Output image path.
8485
ctl_transforms
8586
Sequence of *CTL* transforms to apply on the image, either paths to
86-
existing *CTL* transforms, multi-line *CTL* code transforms or a mix of
87-
both or dictionary of sequence of *CTL* transforms to apply on the
87+
existing *CTL* transforms, multi-line *CTL* code transforms or a mix
88+
of both or dictionary of sequence of *CTL* transforms to apply on the
8889
image and their sequence of parameters.
8990
9091
Other Parameters
9192
----------------
9293
args
9394
Arguments passed to *ctlrender*, e.g., ``-verbose``, ``-force``.
9495
kwargs
95-
Keywords arguments passed to the sub-process calling *ctlrender*, e.g.,
96-
to define the environment variables such as ``CTL_MODULE_PATH``.
97-
98-
Notes
99-
-----
100-
- The multi-line *CTL* code transforms are written to disk in a temporary
101-
location so that they can be used by *ctlrender*.
96+
Keywords arguments passed to the sub-process calling *ctlrender*,
97+
e.g., to define the environment variables such as
98+
``CTL_MODULE_PATH``.
10299
103100
Returns
104101
-------
105102
:class:`subprocess.CompletedProcess`
106103
*ctlrender* process completed output.
107104
105+
Raises
106+
------
107+
FileNotFoundError
108+
If a specified *CTL* transform file does not exist.
109+
110+
Notes
111+
-----
112+
- The multi-line *CTL* code transforms are written to disk in a
113+
temporary location so that they can be used by *ctlrender*.
114+
108115
Examples
109116
--------
110117
>>> ctl_adjust_exposure_float = template_ctl_transform_float(
@@ -206,36 +213,43 @@ def process_image_ctl(
206213
**kwargs: Any,
207214
) -> NDArrayFloat: # pragma: no cover
208215
"""
209-
Process given image data with *ctlrender* using given *CTL* transforms.
216+
Process the specified image data with *ctlrender* using the specified
217+
*CTL* transforms.
210218
211219
Parameters
212220
----------
213221
a
214222
Image data to process with *ctlrender*.
215223
ctl_transforms
216224
Sequence of *CTL* transforms to apply on the image, either paths to
217-
existing *CTL* transforms, multi-line *CTL* code transforms or a mix of
218-
both or dictionary of sequence of *CTL* transforms to apply on the
225+
existing *CTL* transforms, multi-line *CTL* code transforms or a mix
226+
of both or dictionary of sequence of *CTL* transforms to apply on the
219227
image and their sequence of parameters.
220228
221229
Other Parameters
222230
----------------
223231
args
224232
Arguments passed to *ctlrender*, e.g., ``-verbose``, ``-force``.
225233
kwargs
226-
Keywords arguments passed to the sub-process calling *ctlrender*, e.g.,
227-
to define the environment variables such as ``CTL_MODULE_PATH``.
228-
229-
Notes
230-
-----
231-
- The multi-line *CTL* code transforms are written to disk in a temporary
232-
location so that they can be used by *ctlrender*.
234+
Keywords arguments passed to the sub-process calling *ctlrender*,
235+
e.g., to define the environment variables such as
236+
``CTL_MODULE_PATH``.
233237
234238
Returns
235239
-------
236-
:class`numpy.ndarray`
240+
:class:`numpy.ndarray`
237241
Processed image data.
238242
243+
Raises
244+
------
245+
RuntimeError
246+
If the *ctlrender* process returns a non-zero exit code.
247+
248+
Notes
249+
-----
250+
- The multi-line *CTL* code transforms are written to disk in a
251+
temporary location so that they can be used by *ctlrender*.
252+
239253
Examples
240254
--------
241255
>>> from colour.utilities import full
@@ -314,8 +328,8 @@ def template_ctl_transform_float(
314328
header: str | None = None,
315329
) -> str:
316330
"""
317-
Generate the code for a *CTL* transform to test a function processing
318-
per-float channel.
331+
Generate *CTL* transform code for testing a function that processes
332+
per-float channels.
319333
320334
Parameters
321335
----------
@@ -332,7 +346,8 @@ def template_ctl_transform_float(
332346
imports
333347
List of imports to use with the *CTL* transform.
334348
header
335-
Header code that can be used to define various functions and globals.
349+
Header code that can be used to define various functions and
350+
globals.
336351
337352
Returns
338353
-------
@@ -467,8 +482,8 @@ def template_ctl_transform_float3(
467482
header: str | None = None,
468483
) -> str:
469484
"""
470-
Generate the code for a *CTL* transform to test a function processing
471-
RGB channels.
485+
Generate *CTL* transform code for testing a function that processes
486+
*RGB* channels.
472487
473488
Parameters
474489
----------
@@ -481,7 +496,8 @@ def template_ctl_transform_float3(
481496
imports
482497
List of imports to use with the *CTL* transform.
483498
header
484-
Header code that can be used to define various functions and globals.
499+
Header code that can be used to define various functions and
500+
globals.
485501
486502
Returns
487503
-------

‎colour/io/fichet2021.py‎

Lines changed: 37 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -144,7 +144,7 @@ def match_groups_to_nm(
144144
units: Literal["m", "Hz"] | str,
145145
) -> float:
146146
"""
147-
Convert match groups of a wavelength (or frequency) to the nanometer value.
147+
Convert wavelength or frequency match groups to nanometer values.
148148
149149
Parameters
150150
----------
@@ -160,6 +160,11 @@ def match_groups_to_nm(
160160
:class:`float`
161161
Nanometer value.
162162
163+
Raises
164+
------
165+
ValueError
166+
If the multiplier or units are not supported.
167+
163168
Examples
164169
--------
165170
>>> match_groups_to_nm("555.5", "n", "m")
@@ -196,8 +201,8 @@ def sd_to_spectrum_attribute_Fichet2021(
196201
sd: SpectralDistribution, decimals: int = 7
197202
) -> str:
198203
"""
199-
Convert a spectral distribution to a spectrum attribute value according to
200-
*Fichet et al. (2021)*.
204+
Convert the specified spectral distribution to a spectrum attribute value
205+
according to *Fichet et al. (2021)*.
201206
202207
Parameters
203208
----------
@@ -231,8 +236,8 @@ def spectrum_attribute_to_sd_Fichet2021(
231236
spectrum_attribute: str,
232237
) -> SpectralDistribution:
233238
"""
234-
Convert a spectrum attribute value to a spectral distribution according to
235-
*Fichet et al. (2021)*.
239+
Convert the specified spectrum attribute value to a spectral distribution
240+
according to *Fichet et al. (2021)*.
236241
237242
Parameters
238243
----------
@@ -320,8 +325,8 @@ class Specification_Fichet2021:
320325
@required("OpenImageIO")
321326
def from_spectral_image(path: str | PathLike) -> Specification_Fichet2021:
322327
"""
323-
Create a *Fichet et al. (2021)* spectral image specification from given
324-
image path.
328+
Create a *Fichet et al. (2021)* spectral image specification from the
329+
specified image path.
325330
326331
Parameters
327332
----------
@@ -459,7 +464,7 @@ def read_spectral_image_Fichet2021(
459464
additional_data: bool = False,
460465
) -> ComponentsFichet2021 | Tuple[ComponentsFichet2021, Specification_Fichet2021]:
461466
"""
462-
Read the *Fichet et al. (2021)* spectral image at given path using
467+
Read the *Fichet et al. (2021)* spectral image at the specified path using
463468
*OpenImageIO*.
464469
465470
Parameters
@@ -481,8 +486,8 @@ def read_spectral_image_Fichet2021(
481486
Notes
482487
-----
483488
- Spectrum attributes are not parsed but can be converted to spectral
484-
distribution using the :func:`colour.io.spectrum_attribute_to_sd_Fichet2021`
485-
definition.
489+
distribution using the
490+
:func:`colour.io.spectrum_attribute_to_sd_Fichet2021` definition.
486491
487492
References
488493
----------
@@ -550,7 +555,7 @@ def sds_and_msds_to_components_Fichet2021(
550555
**kwargs: Any,
551556
) -> ComponentsFichet2021:
552557
"""
553-
Convert given spectral and multi-spectral distributions to
558+
Convert the specified spectral and multi-spectral distributions to
554559
*Fichet et al. (2021)* components.
555560
556561
The spectral and multi-spectral distributions will be aligned to the
@@ -562,16 +567,16 @@ def sds_and_msds_to_components_Fichet2021(
562567
Spectral and multi-spectral distributions to convert to
563568
*Fichet et al. (2021)* components.
564569
specification
565-
*Fichet et al. (2021)* spectral image specification, used to generate
566-
the proper component type, i.e., emissive or other.
570+
*Fichet et al. (2021)* spectral image specification, used to
571+
generate the proper component type, i.e., emissive or other.
567572
568573
Other Parameters
569574
----------------
570575
shape
571-
Optional shape the *Fichet et al. (2021)* components should take: Used
572-
when converting spectral distributions of a colour
573-
rendition chart to create a rectangular image rather than a single
574-
line of values.
576+
Optional shape the *Fichet et al. (2021)* components should take:
577+
Used when converting spectral distributions of a colour rendition
578+
chart to create a rectangular image rather than a single line of
579+
values.
575580
576581
Returns
577582
-------
@@ -618,7 +623,8 @@ def components_to_sRGB_Fichet2021(
618623
specification: Specification_Fichet2021 = SPECIFICATION_FICHET2021_DEFAULT,
619624
) -> Tuple[NDArrayFloat | None, Sequence[Image_Specification_Attribute]]:
620625
"""
621-
Convert given *Fichet et al. (2021)* components to *sRGB* colourspace values.
626+
Convert the specified *Fichet et al. (2021)* components to *sRGB*
627+
colourspace values.
622628
623629
Parameters
624630
----------
@@ -637,13 +643,13 @@ def components_to_sRGB_Fichet2021(
637643
Warnings
638644
--------
639645
- This definition currently assumes a uniform wavelength interval.
640-
- This definition currently does not support integration of bi-spectral
641-
component.
646+
- This definition currently does not support integration of
647+
bi-spectral component.
642648
643649
Notes
644650
-----
645-
- When an emissive component is given, its exposure will be normalised so
646-
that its median is 0.18.
651+
- When an emissive component is specified, its exposure will be
652+
normalised so that its median is 0.18.
647653
648654
References
649655
----------
@@ -763,7 +769,8 @@ def write_spectral_image_Fichet2021(
763769
**kwargs: Any,
764770
) -> bool:
765771
"""
766-
Write given *Fichet et al. (2021)* components to given path using *OpenImageIO*.
772+
Write the specified *Fichet et al. (2021)* components to the specified
773+
path using *OpenImageIO*.
767774
768775
Parameters
769776
----------
@@ -772,8 +779,8 @@ def write_spectral_image_Fichet2021(
772779
path
773780
Image path.
774781
bit_depth
775-
Bit-depth to write the image at, the bit-depth conversion behaviour is
776-
ruled directly by *OpenImageIO*.
782+
Bit-depth to write the image at, the bit-depth conversion behaviour
783+
is ruled directly by *OpenImageIO*.
777784
specification
778785
*Fichet et al. (2021)* spectral image specification.
779786
components_to_RGB_callable
@@ -782,14 +789,14 @@ def write_spectral_image_Fichet2021(
782789
Other Parameters
783790
----------------
784791
shape
785-
Optional shape the *Fichet et al. (2021)* components should take: Used
786-
when converting spectral distributions of a colour
787-
rendition chart to create a rectangular image rather than a single
788-
line of values.
792+
Optional shape the *Fichet et al. (2021)* components should take:
793+
Used when converting spectral distributions of a colour rendition
794+
chart to create a rectangular image rather than a single line of
795+
values.
789796
790797
Returns
791798
-------
792-
:class:`bool`:
799+
:class:`bool`
793800
Definition success.
794801
795802
Examples

0 commit comments

Comments
 (0)