Skip to content

Commit bb01312

Browse files
radarhereradarhere
committed
Improved formatting
1 parent 8b8b770 commit bb01312

3 files changed

Lines changed: 97 additions & 96 deletions

File tree

‎docs/reference/ImageGrab.rst‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,7 @@ or the clipboard to a PIL image memory.
2626

2727
.. versionadded:: 6.2.0
2828

29-
:param xdisplay: X11 Display address. Pass ``None`` to grab the default system screen.
30-
Pass ``""`` to grab the default X11 screen on Windows or macOS.
29+
:param xdisplay: X11 Display address. Pass ``None`` to grab the default system screen. Pass ``""`` to grab the default X11 screen on Windows or macOS.
3130

3231
.. versionadded:: 7.1.0
3332
:return: An image

‎src/PIL/ImageCms.py‎

Lines changed: 95 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -192,9 +192,9 @@ class ImageCmsTransform(Image.ImagePointHandler):
192192

193193
"""
194194
Transform. This can be used with the procedural API, or with the standard
195-
Image.point() method.
195+
:py:func:`~PIL.Image.Image.point` method.
196196
197-
Will return the output profile in the output.info['icc_profile'].
197+
Will return the output profile in the ``output.info['icc_profile']``.
198198
"""
199199

200200
def __init__(
@@ -251,7 +251,7 @@ def apply_in_place(self, im):
251251

252252
def get_display_profile(handle=None):
253253
""" (experimental) Fetches the profile for the current display device.
254-
:returns: None if the profile is not known.
254+
:returns: ``None`` if the profile is not known.
255255
"""
256256

257257
if sys.platform != "win32":
@@ -292,27 +292,27 @@ def profileToProfile(
292292
):
293293
"""
294294
(pyCMS) Applies an ICC transformation to a given image, mapping from
295-
inputProfile to outputProfile.
295+
``inputProfile`` to ``outputProfile``.
296296
297297
If the input or output profiles specified are not valid filenames, a
298-
PyCMSError will be raised. If inPlace is True and outputMode != im.mode,
299-
a PyCMSError will be raised. If an error occurs during application of
300-
the profiles, a PyCMSError will be raised. If outputMode is not a mode
301-
supported by the outputProfile (or by pyCMS), a PyCMSError will be
302-
raised.
303-
304-
This function applies an ICC transformation to im from inputProfile's
305-
color space to outputProfile's color space using the specified rendering
298+
**PyCMSError** will be raised. If ``inPlace`` is ``True`` and
299+
``outputMode != im.mode``, a **PyCMSError** will be raised. If an error
300+
occurs during application of the profiles, a **PyCMSError** will be raised.
301+
If ``outputMode`` is not a mode supported by the ``outputProfile`` (or by pyCMS),
302+
a **PyCMSError** will be raised.
303+
304+
This function applies an ICC transformation to im from ``inputProfile``'s
305+
color space to ``outputProfile``'s color space using the specified rendering
306306
intent to decide how to handle out-of-gamut colors.
307307
308-
OutputMode can be used to specify that a color mode conversion is to
308+
``outputMode`` can be used to specify that a color mode conversion is to
309309
be done using these profiles, but the specified profiles must be able
310310
to handle that mode. I.e., if converting im from RGB to CMYK using
311311
profiles, the input profile must handle RGB data, and the output
312312
profile must handle CMYK data.
313313
314-
:param im: An open PIL image object (i.e. Image.new(...) or
315-
Image.open(...), etc.)
314+
:param im: An open :py:class:`~PIL.Image.Image` object (i.e. Image.new(...)
315+
or Image.open(...), etc.)
316316
:param inputProfile: String, as a valid filename path to the ICC input
317317
profile you wish to use for this image, or a profile object
318318
:param outputProfile: String, as a valid filename path to the ICC output
@@ -332,12 +332,12 @@ def profileToProfile(
332332
MUST be the same mode as the input, or omitted completely. If
333333
omitted, the outputMode will be the same as the mode of the input
334334
image (im.mode)
335-
:param inPlace: Boolean. If True, the original image is modified in-place,
336-
and None is returned. If False (default), a new Image object is
337-
returned with the transform applied.
335+
:param inPlace: Boolean. If ``True``, the original image is modified in-place,
336+
and ``None`` is returned. If ``False`` (default), a new
337+
:py:class:`~PIL.Image.Image` object is returned with the transform applied.
338338
:param flags: Integer (0-...) specifying additional flags
339-
:returns: Either None or a new PIL image object, depending on value of
340-
inPlace
339+
:returns: Either None or a new :py:class:`~PIL.Image.Image` object, depending on
340+
the value of ``inPlace``
341341
:exception PyCMSError:
342342
"""
343343

@@ -381,7 +381,7 @@ def getOpenProfile(profileFilename):
381381
The PyCMSProfile object can be passed back into pyCMS for use in creating
382382
transforms and such (as in ImageCms.buildTransformFromOpenProfiles()).
383383
384-
If profileFilename is not a valid filename for an ICC profile, a PyCMSError
384+
If ``profileFilename`` is not a valid filename for an ICC profile, a **PyCMSError**
385385
will be raised.
386386
387387
:param profileFilename: String, as a valid filename path to the ICC profile
@@ -405,21 +405,21 @@ def buildTransform(
405405
flags=0,
406406
):
407407
"""
408-
(pyCMS) Builds an ICC transform mapping from the inputProfile to the
409-
outputProfile. Use applyTransform to apply the transform to a given
408+
(pyCMS) Builds an ICC transform mapping from the ``inputProfile`` to the
409+
``outputProfile``. Use applyTransform to apply the transform to a given
410410
image.
411411
412412
If the input or output profiles specified are not valid filenames, a
413-
PyCMSError will be raised. If an error occurs during creation of the
414-
transform, a PyCMSError will be raised.
413+
**PyCMSError** will be raised. If an error occurs during creation of the
414+
transform, a **PyCMSError** will be raised.
415415
416-
If inMode or outMode are not a mode supported by the outputProfile (or
417-
by pyCMS), a PyCMSError will be raised.
416+
If ``inMode`` or ``outMode`` are not a mode supported by the ``outputProfile``
417+
(or by pyCMS), a **PyCMSError** will be raised.
418418
419-
This function builds and returns an ICC transform from the inputProfile
420-
to the outputProfile using the renderingIntent to determine what to do
419+
This function builds and returns an ICC transform from the ``inputProfile``
420+
to the ``outputProfile`` using the ``renderingIntent`` to determine what to do
421421
with out-of-gamut colors. It will ONLY work for converting images that
422-
are in inMode to images that are in outMode color format (PIL mode,
422+
are in ``inMode`` to images that are in ``outMode`` color format (PIL mode,
423423
i.e. "RGB", "RGBA", "CMYK", etc.).
424424
425425
Building the transform is a fair part of the overhead in
@@ -432,7 +432,7 @@ def buildTransform(
432432
The reason pyCMS returns a class object rather than a handle directly
433433
to the transform is that it needs to keep track of the PIL input/output
434434
modes that the transform is meant for. These attributes are stored in
435-
the "inMode" and "outMode" attributes of the object (which can be
435+
the ``inMode`` and ``outMode`` attributes of the object (which can be
436436
manually overridden if you really want to, but I don't know of any
437437
time that would be of use, or would even work).
438438
@@ -488,33 +488,33 @@ def buildProofTransform(
488488
flags=FLAGS["SOFTPROOFING"],
489489
):
490490
"""
491-
(pyCMS) Builds an ICC transform mapping from the inputProfile to the
492-
outputProfile, but tries to simulate the result that would be
493-
obtained on the proofProfile device.
491+
(pyCMS) Builds an ICC transform mapping from the ``inputProfile`` to the
492+
``outputProfile``, but tries to simulate the result that would be
493+
obtained on the ``proofProfile`` device.
494494
495495
If the input, output, or proof profiles specified are not valid
496-
filenames, a PyCMSError will be raised.
496+
filenames, a **PyCMSError** will be raised.
497497
498-
If an error occurs during creation of the transform, a PyCMSError will
499-
be raised.
498+
If an error occurs during creation of the transform, a **PyCMSError**
499+
will be raised.
500500
501-
If inMode or outMode are not a mode supported by the outputProfile
502-
(or by pyCMS), a PyCMSError will be raised.
501+
If ``inMode`` or ``outMode`` are not a mode supported by the ``outputProfile``
502+
(or by pyCMS), a **PyCMSError** will be raised.
503503
504-
This function builds and returns an ICC transform from the inputProfile
505-
to the outputProfile, but tries to simulate the result that would be
506-
obtained on the proofProfile device using renderingIntent and
507-
proofRenderingIntent to determine what to do with out-of-gamut
504+
This function builds and returns an ICC transform from the ``inputProfile``
505+
to the ``outputProfile``, but tries to simulate the result that would be
506+
obtained on the ``proofProfile`` device using ``renderingIntent`` and
507+
``proofRenderingIntent`` to determine what to do with out-of-gamut
508508
colors. This is known as "soft-proofing". It will ONLY work for
509-
converting images that are in inMode to images that are in outMode
509+
converting images that are in ``inMode`` to images that are in outMode
510510
color format (PIL mode, i.e. "RGB", "RGBA", "CMYK", etc.).
511511
512512
Usage of the resulting transform object is exactly the same as with
513513
ImageCms.buildTransform().
514514
515515
Proof profiling is generally used when using an output device to get a
516516
good idea of what the final printed/displayed image would look like on
517-
the proofProfile device when it's quicker and easier to use the
517+
the ``proofProfile`` device when it's quicker and easier to use the
518518
output device for judging color. Generally, this means that the
519519
output device is a monitor, or a dye-sub printer (etc.), and the simulated
520520
device is something more expensive, complicated, or time consuming
@@ -596,39 +596,40 @@ def applyTransform(im, transform, inPlace=False):
596596
"""
597597
(pyCMS) Applies a transform to a given image.
598598
599-
If im.mode != transform.inMode, a PyCMSError is raised.
599+
If ``im.mode != transform.inMode``, a **PyCMSError** is raised.
600600
601-
If inPlace is True and transform.inMode != transform.outMode, a
602-
PyCMSError is raised.
601+
If ``inPlace`` is ``True`` and ``transform.inMode != transform.outMode``, a
602+
**PyCMSError** is raised.
603603
604-
If im.mode, transform.inMode, or transform.outMode is not supported by
605-
pyCMSdll or the profiles you used for the transform, a PyCMSError is
606-
raised.
604+
If ``im.mode``, ``transform.inMode`` or ``transform.outMode`` is not
605+
supported by pyCMSdll or the profiles you used for the transform, a
606+
**PyCMSError** is raised.
607607
608-
If an error occurs while the transform is being applied, a PyCMSError
608+
If an error occurs while the transform is being applied, a **PyCMSError**
609609
is raised.
610610
611611
This function applies a pre-calculated transform (from
612612
ImageCms.buildTransform() or ImageCms.buildTransformFromOpenProfiles())
613-
to an image. The transform can be used for multiple images, saving
613+
to an image. The transform can be used for multiple images, saving
614614
considerable calculation time if doing the same conversion multiple times.
615615
616616
If you want to modify im in-place instead of receiving a new image as
617-
the return value, set inPlace to True. This can only be done if
618-
transform.inMode and transform.outMode are the same, because we can't
617+
the return value, set ``inPlace`` to ``True``. This can only be done if
618+
``transform.inMode`` and ``transform.outMode`` are the same, because we can't
619619
change the mode in-place (the buffer sizes for some modes are
620-
different). The default behavior is to return a new Image object of
621-
the same dimensions in mode transform.outMode.
620+
different). The default behavior is to return a new :py:class:`~PIL.Image.Image`
621+
object of the same dimensions in mode ``transform.outMode``.
622622
623-
:param im: A PIL Image object, and im.mode must be the same as the inMode
624-
supported by the transform.
623+
:param im: An :py:class:`~PIL.Image.Image` object, and im.mode must be the same
624+
as the ``inMode`` supported by the transform.
625625
:param transform: A valid CmsTransform class object
626-
:param inPlace: Bool. If True, im is modified in place and None is
627-
returned, if False, a new Image object with the transform applied is
628-
returned (and im is not changed). The default is False.
629-
:returns: Either None, or a new PIL Image object, depending on the value of
630-
inPlace. The profile will be returned in the image's
631-
info['icc_profile'].
626+
:param inPlace: Bool. If ``True``, ``im` is modified in place and ``None`` is
627+
returned, if ``False``, a new :py:class:`~PIL.Image.Image` object with the
628+
transform applied is returned (and ``im`` is not changed). The default is
629+
``False``.
630+
:returns: Either ``None``, or a new :py:class:`~PIL.Image.Image` object,
631+
depending on the value of ``inPlace``. The profile will be returned in
632+
the image's ``info['icc_profile']``.
632633
:exception PyCMSError:
633634
"""
634635

@@ -648,11 +649,12 @@ def createProfile(colorSpace, colorTemp=-1):
648649
"""
649650
(pyCMS) Creates a profile.
650651
651-
If colorSpace not in ["LAB", "XYZ", "sRGB"], a PyCMSError is raised
652+
If colorSpace not in ``["LAB", "XYZ", "sRGB"]``, a **PyCMSError** is raised
652653
653-
If using LAB and colorTemp != a positive integer, a PyCMSError is raised.
654+
If using LAB and ``colorTemp`` is not a positive integer, a **PyCMSError** is
655+
raised.
654656
655-
If an error occurs while creating the profile, a PyCMSError is raised.
657+
If an error occurs while creating the profile, a **PyCMSError** is raised.
656658
657659
Use this function to create common profiles on-the-fly instead of
658660
having to supply a profile on disk and knowing the path to it. It
@@ -696,9 +698,9 @@ def getProfileName(profile):
696698
697699
(pyCMS) Gets the internal product name for the given profile.
698700
699-
If profile isn't a valid CmsProfile object or filename to a profile,
700-
a PyCMSError is raised If an error occurs while trying to obtain the
701-
name tag, a PyCMSError is raised.
701+
If ``profile`` isn't a valid CmsProfile object or filename to a profile,
702+
a **PyCMSError** is raised If an error occurs while trying to obtain the
703+
name tag, a **PyCMSError** is raised.
702704
703705
Use this function to obtain the INTERNAL name of the profile (stored
704706
in an ICC tag in the profile itself), usually the one used when the
@@ -737,10 +739,10 @@ def getProfileInfo(profile):
737739
"""
738740
(pyCMS) Gets the internal product information for the given profile.
739741
740-
If profile isn't a valid CmsProfile object or filename to a profile,
741-
a PyCMSError is raised.
742+
If ``profile`` isn't a valid CmsProfile object or filename to a profile,
743+
a **PyCMSError** is raised.
742744
743-
If an error occurs while trying to obtain the info tag, a PyCMSError
745+
If an error occurs while trying to obtain the info tag, a **PyCMSError**
744746
is raised
745747
746748
Use this function to obtain the information stored in the profile's
@@ -777,10 +779,10 @@ def getProfileCopyright(profile):
777779
"""
778780
(pyCMS) Gets the copyright for the given profile.
779781
780-
If profile isn't a valid CmsProfile object or filename to a profile,
781-
a PyCMSError is raised.
782+
If ``profile`` isn't a valid CmsProfile object or filename to a profile, a
783+
**PyCMSError** is raised.
782784
783-
If an error occurs while trying to obtain the copyright tag, a PyCMSError
785+
If an error occurs while trying to obtain the copyright tag, a **PyCMSError**
784786
is raised
785787
786788
Use this function to obtain the information stored in the profile's
@@ -805,11 +807,11 @@ def getProfileManufacturer(profile):
805807
"""
806808
(pyCMS) Gets the manufacturer for the given profile.
807809
808-
If profile isn't a valid CmsProfile object or filename to a profile,
809-
a PyCMSError is raised.
810+
If ``profile`` isn't a valid CmsProfile object or filename to a profile, a
811+
**PyCMSError** is raised.
810812
811813
If an error occurs while trying to obtain the manufacturer tag, a
812-
PyCMSError is raised
814+
**PyCMSError** is raised
813815
814816
Use this function to obtain the information stored in the profile's
815817
manufacturer tag.
@@ -833,10 +835,10 @@ def getProfileModel(profile):
833835
"""
834836
(pyCMS) Gets the model for the given profile.
835837
836-
If profile isn't a valid CmsProfile object or filename to a profile,
837-
a PyCMSError is raised.
838+
If ``profile`` isn't a valid CmsProfile object or filename to a profile, a
839+
**PyCMSError** is raised.
838840
839-
If an error occurs while trying to obtain the model tag, a PyCMSError
841+
If an error occurs while trying to obtain the model tag, a **PyCMSError**
840842
is raised
841843
842844
Use this function to obtain the information stored in the profile's
@@ -862,10 +864,10 @@ def getProfileDescription(profile):
862864
"""
863865
(pyCMS) Gets the description for the given profile.
864866
865-
If profile isn't a valid CmsProfile object or filename to a profile,
866-
a PyCMSError is raised.
867+
If ``profile`` isn't a valid CmsProfile object or filename to a profile, a
868+
**PyCMSError** is raised.
867869
868-
If an error occurs while trying to obtain the description tag, a PyCMSError
870+
If an error occurs while trying to obtain the description tag, a **PyCMSError**
869871
is raised
870872
871873
Use this function to obtain the information stored in the profile's
@@ -891,11 +893,11 @@ def getDefaultIntent(profile):
891893
"""
892894
(pyCMS) Gets the default intent name for the given profile.
893895
894-
If profile isn't a valid CmsProfile object or filename to a profile,
895-
a PyCMSError is raised.
896+
If ``profile`` isn't a valid CmsProfile object or filename to a profile, a
897+
**PyCMSError** is raised.
896898
897899
If an error occurs while trying to obtain the default intent, a
898-
PyCMSError is raised.
900+
**PyCMSError** is raised.
899901
900902
Use this function to determine the default (and usually best optimized)
901903
rendering intent for this profile. Most profiles support multiple
@@ -931,14 +933,14 @@ def isIntentSupported(profile, intent, direction):
931933
(pyCMS) Checks if a given intent is supported.
932934
933935
Use this function to verify that you can use your desired
934-
renderingIntent with profile, and that profile can be used for the
936+
``intent`` with ``profile``, and that ``profile`` can be used for the
935937
input/output/proof profile as you desire.
936938
937939
Some profiles are created specifically for one "direction", can cannot
938-
be used for others. Some profiles can only be used for certain
939-
rendering intents... so it's best to either verify this before trying
940+
be used for others. Some profiles can only be used for certain
941+
rendering intents, so it's best to either verify this before trying
940942
to create a transform with them (using this function), or catch the
941-
potential PyCMSError that will occur if they don't support the modes
943+
potential **PyCMSError** that will occur if they don't support the modes
942944
you select.
943945
944946
:param profile: EITHER a valid CmsProfile object, OR a string of the

‎src/PIL/ImageWin.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -173,7 +173,7 @@ def frombytes(self, buffer):
173173
Load display memory contents from byte data.
174174
175175
:param buffer: A buffer containing display data (usually
176-
data returned from <b>tobytes</b>)
176+
data returned from :py:func:`~PIL.ImageWin.Dib.tobytes`)
177177
"""
178178
return self.image.frombytes(buffer)
179179

0 commit comments

Comments
 (0)