python-pillow/Pillow
1
1
Fork 0
mirror of https://github.com/python-pillow/Pillow.git synced 2025-02-04 21:50:54 +03:00
Code Issues Packages Projects Releases Wiki Activity

Improved formatting

Browse Source
This commit is contained in:
Andrew Murray 2020-06-11 22:42:13 +10:00
parent 8b8b770b8a
commit bb01312ba9
3 changed files with 96 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/reference/ImageGrab.rst
View File

@ -26,8 +26,7 @@ or the clipboard to a PIL image memory.
.. versionadded:: 6.2.0 .. versionadded:: 6.2.0
:param xdisplay: X11 Display address. Pass ``None`` to grab the default system screen. :param xdisplay: X11 Display address. Pass ``None`` to grab the default system screen. Pass ``""`` to grab the default X11 screen on Windows or macOS.
Pass ``""`` to grab the default X11 screen on Windows or macOS.
.. versionadded:: 7.1.0 .. versionadded:: 7.1.0
:return: An image :return: An image

186
src/PIL/ImageCms.py
View File

@ -192,9 +192,9 @@ class ImageCmsTransform(Image.ImagePointHandler):
""" """
Transform. This can be used with the procedural API, or with the standard Transform. This can be used with the procedural API, or with the standard
Image.point() method. :py:func:`~PIL.Image.Image.point` method.
Will return the output profile in the output.info['icc_profile']. Will return the output profile in the ``output.info['icc_profile']``.
""" """
def __init__( def __init__(
@ -251,7 +251,7 @@ class ImageCmsTransform(Image.ImagePointHandler):
def get_display_profile(handle=None): def get_display_profile(handle=None):
""" (experimental) Fetches the profile for the current display device. """ (experimental) Fetches the profile for the current display device.
:returns: None if the profile is not known. :returns: ``None`` if the profile is not known.
""" """
if sys.platform != "win32": if sys.platform != "win32":
@ -292,27 +292,27 @@ def profileToProfile(
): ):
""" """
(pyCMS) Applies an ICC transformation to a given image, mapping from (pyCMS) Applies an ICC transformation to a given image, mapping from
inputProfile to outputProfile. ``inputProfile`` to ``outputProfile``.
If the input or output profiles specified are not valid filenames, a If the input or output profiles specified are not valid filenames, a
PyCMSError will be raised. If inPlace is True and outputMode != im.mode, **PyCMSError** will be raised. If ``inPlace`` is ``True`` and
a PyCMSError will be raised. If an error occurs during application of ``outputMode != im.mode``, a **PyCMSError** will be raised. If an error
the profiles, a PyCMSError will be raised. If outputMode is not a mode occurs during application of the profiles, a **PyCMSError** will be raised.
supported by the outputProfile (or by pyCMS), a PyCMSError will be If ``outputMode`` is not a mode supported by the ``outputProfile`` (or by pyCMS),
raised. a **PyCMSError** will be raised.
This function applies an ICC transformation to im from inputProfile's This function applies an ICC transformation to im from ``inputProfile``'s
color space to outputProfile's color space using the specified rendering color space to ``outputProfile``'s color space using the specified rendering
intent to decide how to handle out-of-gamut colors. intent to decide how to handle out-of-gamut colors.
OutputMode can be used to specify that a color mode conversion is to ``outputMode`` can be used to specify that a color mode conversion is to
be done using these profiles, but the specified profiles must be able be done using these profiles, but the specified profiles must be able
to handle that mode. I.e., if converting im from RGB to CMYK using to handle that mode. I.e., if converting im from RGB to CMYK using
profiles, the input profile must handle RGB data, and the output profiles, the input profile must handle RGB data, and the output
profile must handle CMYK data. profile must handle CMYK data.
:param im: An open PIL image object (i.e. Image.new(...) or :param im: An open :py:class:`~PIL.Image.Image` object (i.e. Image.new(...)
Image.open(...), etc.) or Image.open(...), etc.)
:param inputProfile: String, as a valid filename path to the ICC input :param inputProfile: String, as a valid filename path to the ICC input
profile you wish to use for this image, or a profile object profile you wish to use for this image, or a profile object
:param outputProfile: String, as a valid filename path to the ICC output :param outputProfile: String, as a valid filename path to the ICC output
@ -332,12 +332,12 @@ def profileToProfile(
MUST be the same mode as the input, or omitted completely. If MUST be the same mode as the input, or omitted completely. If
omitted, the outputMode will be the same as the mode of the input omitted, the outputMode will be the same as the mode of the input
image (im.mode) image (im.mode)
:param inPlace: Boolean. If True, the original image is modified in-place, :param inPlace: Boolean. If ``True``, the original image is modified in-place,
and None is returned. If False (default), a new Image object is and ``None`` is returned. If ``False`` (default), a new
returned with the transform applied. :py:class:`~PIL.Image.Image` object is returned with the transform applied.
:param flags: Integer (0-...) specifying additional flags :param flags: Integer (0-...) specifying additional flags
:returns: Either None or a new PIL image object, depending on value of :returns: Either None or a new :py:class:`~PIL.Image.Image` object, depending on
inPlace the value of ``inPlace``
:exception PyCMSError: :exception PyCMSError:
""" """
@ -381,7 +381,7 @@ def getOpenProfile(profileFilename):
The PyCMSProfile object can be passed back into pyCMS for use in creating The PyCMSProfile object can be passed back into pyCMS for use in creating
transforms and such (as in ImageCms.buildTransformFromOpenProfiles()). transforms and such (as in ImageCms.buildTransformFromOpenProfiles()).
If profileFilename is not a valid filename for an ICC profile, a PyCMSError If ``profileFilename`` is not a valid filename for an ICC profile, a **PyCMSError**
will be raised. will be raised.
:param profileFilename: String, as a valid filename path to the ICC profile :param profileFilename: String, as a valid filename path to the ICC profile
@ -405,21 +405,21 @@ def buildTransform(
flags=0, flags=0,
): ):
""" """
(pyCMS) Builds an ICC transform mapping from the inputProfile to the (pyCMS) Builds an ICC transform mapping from the ``inputProfile`` to the
outputProfile. Use applyTransform to apply the transform to a given ``outputProfile``. Use applyTransform to apply the transform to a given
image. image.
If the input or output profiles specified are not valid filenames, a If the input or output profiles specified are not valid filenames, a
PyCMSError will be raised. If an error occurs during creation of the **PyCMSError** will be raised. If an error occurs during creation of the
transform, a PyCMSError will be raised. transform, a **PyCMSError** will be raised.
If inMode or outMode are not a mode supported by the outputProfile (or If ``inMode`` or ``outMode`` are not a mode supported by the ``outputProfile``
by pyCMS), a PyCMSError will be raised. (or by pyCMS), a **PyCMSError** will be raised.
This function builds and returns an ICC transform from the inputProfile This function builds and returns an ICC transform from the ``inputProfile``
to the outputProfile using the renderingIntent to determine what to do to the ``outputProfile`` using the ``renderingIntent`` to determine what to do
with out-of-gamut colors. It will ONLY work for converting images that with out-of-gamut colors. It will ONLY work for converting images that
are in inMode to images that are in outMode color format (PIL mode, are in ``inMode`` to images that are in ``outMode`` color format (PIL mode,
i.e. "RGB", "RGBA", "CMYK", etc.). i.e. "RGB", "RGBA", "CMYK", etc.).
Building the transform is a fair part of the overhead in Building the transform is a fair part of the overhead in
@ -432,7 +432,7 @@ def buildTransform(
The reason pyCMS returns a class object rather than a handle directly The reason pyCMS returns a class object rather than a handle directly
to the transform is that it needs to keep track of the PIL input/output to the transform is that it needs to keep track of the PIL input/output
modes that the transform is meant for. These attributes are stored in modes that the transform is meant for. These attributes are stored in
the "inMode" and "outMode" attributes of the object (which can be the ``inMode`` and ``outMode`` attributes of the object (which can be
manually overridden if you really want to, but I don't know of any manually overridden if you really want to, but I don't know of any
time that would be of use, or would even work). time that would be of use, or would even work).
@ -488,25 +488,25 @@ def buildProofTransform(
flags=FLAGS["SOFTPROOFING"], flags=FLAGS["SOFTPROOFING"],
): ):
""" """
(pyCMS) Builds an ICC transform mapping from the inputProfile to the (pyCMS) Builds an ICC transform mapping from the ``inputProfile`` to the
outputProfile, but tries to simulate the result that would be ``outputProfile``, but tries to simulate the result that would be
obtained on the proofProfile device. obtained on the ``proofProfile`` device.
If the input, output, or proof profiles specified are not valid If the input, output, or proof profiles specified are not valid
filenames, a PyCMSError will be raised. filenames, a **PyCMSError** will be raised.
If an error occurs during creation of the transform, a PyCMSError will If an error occurs during creation of the transform, a **PyCMSError**
be raised. will be raised.
If inMode or outMode are not a mode supported by the outputProfile If ``inMode`` or ``outMode`` are not a mode supported by the ``outputProfile``
(or by pyCMS), a PyCMSError will be raised. (or by pyCMS), a **PyCMSError** will be raised.
This function builds and returns an ICC transform from the inputProfile This function builds and returns an ICC transform from the ``inputProfile``
to the outputProfile, but tries to simulate the result that would be to the ``outputProfile``, but tries to simulate the result that would be
obtained on the proofProfile device using renderingIntent and obtained on the ``proofProfile`` device using ``renderingIntent`` and
proofRenderingIntent to determine what to do with out-of-gamut ``proofRenderingIntent`` to determine what to do with out-of-gamut
colors. This is known as "soft-proofing". It will ONLY work for colors. This is known as "soft-proofing". It will ONLY work for
converting images that are in inMode to images that are in outMode converting images that are in ``inMode`` to images that are in outMode
color format (PIL mode, i.e. "RGB", "RGBA", "CMYK", etc.). color format (PIL mode, i.e. "RGB", "RGBA", "CMYK", etc.).
Usage of the resulting transform object is exactly the same as with Usage of the resulting transform object is exactly the same as with
@ -514,7 +514,7 @@ def buildProofTransform(
Proof profiling is generally used when using an output device to get a Proof profiling is generally used when using an output device to get a
good idea of what the final printed/displayed image would look like on good idea of what the final printed/displayed image would look like on
the proofProfile device when it's quicker and easier to use the the ``proofProfile`` device when it's quicker and easier to use the
output device for judging color. Generally, this means that the output device for judging color. Generally, this means that the
output device is a monitor, or a dye-sub printer (etc.), and the simulated output device is a monitor, or a dye-sub printer (etc.), and the simulated
device is something more expensive, complicated, or time consuming device is something more expensive, complicated, or time consuming
@ -596,39 +596,40 @@ def applyTransform(im, transform, inPlace=False):
""" """
(pyCMS) Applies a transform to a given image. (pyCMS) Applies a transform to a given image.
If im.mode != transform.inMode, a PyCMSError is raised. If ``im.mode != transform.inMode``, a **PyCMSError** is raised.
If inPlace is True and transform.inMode != transform.outMode, a If ``inPlace`` is ``True`` and ``transform.inMode != transform.outMode``, a
PyCMSError is raised. **PyCMSError** is raised.
If im.mode, transform.inMode, or transform.outMode is not supported by If ``im.mode``, ``transform.inMode`` or ``transform.outMode`` is not
pyCMSdll or the profiles you used for the transform, a PyCMSError is supported by pyCMSdll or the profiles you used for the transform, a
raised. **PyCMSError** is raised.
If an error occurs while the transform is being applied, a PyCMSError If an error occurs while the transform is being applied, a **PyCMSError**
is raised. is raised.
This function applies a pre-calculated transform (from This function applies a pre-calculated transform (from
ImageCms.buildTransform() or ImageCms.buildTransformFromOpenProfiles()) ImageCms.buildTransform() or ImageCms.buildTransformFromOpenProfiles())
to an image. The transform can be used for multiple images, saving to an image. The transform can be used for multiple images, saving
considerable calculation time if doing the same conversion multiple times. considerable calculation time if doing the same conversion multiple times.
If you want to modify im in-place instead of receiving a new image as If you want to modify im in-place instead of receiving a new image as
the return value, set inPlace to True. This can only be done if the return value, set ``inPlace`` to ``True``. This can only be done if
transform.inMode and transform.outMode are the same, because we can't ``transform.inMode`` and ``transform.outMode`` are the same, because we can't
change the mode in-place (the buffer sizes for some modes are change the mode in-place (the buffer sizes for some modes are
different). The default behavior is to return a new Image object of different). The default behavior is to return a new :py:class:`~PIL.Image.Image`
the same dimensions in mode transform.outMode. object of the same dimensions in mode ``transform.outMode``.
:param im: A PIL Image object, and im.mode must be the same as the inMode :param im: An :py:class:`~PIL.Image.Image` object, and im.mode must be the same
supported by the transform. as the ``inMode`` supported by the transform.
:param transform: A valid CmsTransform class object :param transform: A valid CmsTransform class object
:param inPlace: Bool. If True, im is modified in place and None is :param inPlace: Bool. If ``True``, ``im` is modified in place and ``None`` is
returned, if False, a new Image object with the transform applied is returned, if ``False``, a new :py:class:`~PIL.Image.Image` object with the
returned (and im is not changed). The default is False. transform applied is returned (and ``im`` is not changed). The default is
:returns: Either None, or a new PIL Image object, depending on the value of ``False``.
inPlace. The profile will be returned in the image's :returns: Either ``None``, or a new :py:class:`~PIL.Image.Image` object,
info['icc_profile']. depending on the value of ``inPlace``. The profile will be returned in
the image's ``info['icc_profile']``.
:exception PyCMSError: :exception PyCMSError:
""" """
@ -648,11 +649,12 @@ def createProfile(colorSpace, colorTemp=-1):
""" """
(pyCMS) Creates a profile. (pyCMS) Creates a profile.
If colorSpace not in ["LAB", "XYZ", "sRGB"], a PyCMSError is raised If colorSpace not in ``["LAB", "XYZ", "sRGB"]``, a **PyCMSError** is raised
If using LAB and colorTemp != a positive integer, a PyCMSError is raised. If using LAB and ``colorTemp`` is not a positive integer, a **PyCMSError** is
raised.
If an error occurs while creating the profile, a PyCMSError is raised. If an error occurs while creating the profile, a **PyCMSError** is raised.
Use this function to create common profiles on-the-fly instead of Use this function to create common profiles on-the-fly instead of
having to supply a profile on disk and knowing the path to it. It having to supply a profile on disk and knowing the path to it. It
@ -696,9 +698,9 @@ def getProfileName(profile):
(pyCMS) Gets the internal product name for the given profile. (pyCMS) Gets the internal product name for the given profile.
If profile isn't a valid CmsProfile object or filename to a profile, If ``profile`` isn't a valid CmsProfile object or filename to a profile,
a PyCMSError is raised If an error occurs while trying to obtain the a **PyCMSError** is raised If an error occurs while trying to obtain the
name tag, a PyCMSError is raised. name tag, a **PyCMSError** is raised.
Use this function to obtain the INTERNAL name of the profile (stored Use this function to obtain the INTERNAL name of the profile (stored
in an ICC tag in the profile itself), usually the one used when the in an ICC tag in the profile itself), usually the one used when the
@ -737,10 +739,10 @@ def getProfileInfo(profile):
""" """
(pyCMS) Gets the internal product information for the given profile. (pyCMS) Gets the internal product information for the given profile.
If profile isn't a valid CmsProfile object or filename to a profile, If ``profile`` isn't a valid CmsProfile object or filename to a profile,
a PyCMSError is raised. a **PyCMSError** is raised.
If an error occurs while trying to obtain the info tag, a PyCMSError If an error occurs while trying to obtain the info tag, a **PyCMSError**
is raised is raised
Use this function to obtain the information stored in the profile's Use this function to obtain the information stored in the profile's
@ -777,10 +779,10 @@ def getProfileCopyright(profile):
""" """
(pyCMS) Gets the copyright for the given profile. (pyCMS) Gets the copyright for the given profile.
If profile isn't a valid CmsProfile object or filename to a profile, If ``profile`` isn't a valid CmsProfile object or filename to a profile, a
a PyCMSError is raised. **PyCMSError** is raised.
If an error occurs while trying to obtain the copyright tag, a PyCMSError If an error occurs while trying to obtain the copyright tag, a **PyCMSError**
is raised is raised
Use this function to obtain the information stored in the profile's Use this function to obtain the information stored in the profile's
@ -805,11 +807,11 @@ def getProfileManufacturer(profile):
""" """
(pyCMS) Gets the manufacturer for the given profile. (pyCMS) Gets the manufacturer for the given profile.
If profile isn't a valid CmsProfile object or filename to a profile, If ``profile`` isn't a valid CmsProfile object or filename to a profile, a
a PyCMSError is raised. **PyCMSError** is raised.
If an error occurs while trying to obtain the manufacturer tag, a If an error occurs while trying to obtain the manufacturer tag, a
PyCMSError is raised **PyCMSError** is raised
Use this function to obtain the information stored in the profile's Use this function to obtain the information stored in the profile's
manufacturer tag. manufacturer tag.
@ -833,10 +835,10 @@ def getProfileModel(profile):
""" """
(pyCMS) Gets the model for the given profile. (pyCMS) Gets the model for the given profile.
If profile isn't a valid CmsProfile object or filename to a profile, If ``profile`` isn't a valid CmsProfile object or filename to a profile, a
a PyCMSError is raised. **PyCMSError** is raised.
If an error occurs while trying to obtain the model tag, a PyCMSError If an error occurs while trying to obtain the model tag, a **PyCMSError**
is raised is raised
Use this function to obtain the information stored in the profile's Use this function to obtain the information stored in the profile's
@ -862,10 +864,10 @@ def getProfileDescription(profile):
""" """
(pyCMS) Gets the description for the given profile. (pyCMS) Gets the description for the given profile.
If profile isn't a valid CmsProfile object or filename to a profile, If ``profile`` isn't a valid CmsProfile object or filename to a profile, a
a PyCMSError is raised. **PyCMSError** is raised.
If an error occurs while trying to obtain the description tag, a PyCMSError If an error occurs while trying to obtain the description tag, a **PyCMSError**
is raised is raised
Use this function to obtain the information stored in the profile's Use this function to obtain the information stored in the profile's
@ -891,11 +893,11 @@ def getDefaultIntent(profile):
""" """
(pyCMS) Gets the default intent name for the given profile. (pyCMS) Gets the default intent name for the given profile.
If profile isn't a valid CmsProfile object or filename to a profile, If ``profile`` isn't a valid CmsProfile object or filename to a profile, a
a PyCMSError is raised. **PyCMSError** is raised.
If an error occurs while trying to obtain the default intent, a If an error occurs while trying to obtain the default intent, a
PyCMSError is raised. **PyCMSError** is raised.
Use this function to determine the default (and usually best optimized) Use this function to determine the default (and usually best optimized)
rendering intent for this profile. Most profiles support multiple rendering intent for this profile. Most profiles support multiple
@ -931,14 +933,14 @@ def isIntentSupported(profile, intent, direction):
(pyCMS) Checks if a given intent is supported. (pyCMS) Checks if a given intent is supported.
Use this function to verify that you can use your desired Use this function to verify that you can use your desired
renderingIntent with profile, and that profile can be used for the ``intent`` with ``profile``, and that ``profile`` can be used for the
input/output/proof profile as you desire. input/output/proof profile as you desire.
Some profiles are created specifically for one "direction", can cannot Some profiles are created specifically for one "direction", can cannot
be used for others. Some profiles can only be used for certain be used for others. Some profiles can only be used for certain
rendering intents... so it's best to either verify this before trying rendering intents, so it's best to either verify this before trying
to create a transform with them (using this function), or catch the to create a transform with them (using this function), or catch the
potential PyCMSError that will occur if they don't support the modes potential **PyCMSError** that will occur if they don't support the modes
you select. you select.
:param profile: EITHER a valid CmsProfile object, OR a string of the :param profile: EITHER a valid CmsProfile object, OR a string of the

2
src/PIL/ImageWin.py
View File

@ -173,7 +173,7 @@ class Dib:
Load display memory contents from byte data. Load display memory contents from byte data.
:param buffer: A buffer containing display data (usually :param buffer: A buffer containing display data (usually
data returned from <b>tobytes</b>) data returned from :py:func:`~PIL.ImageWin.Dib.tobytes`)
""" """
return self.image.frombytes(buffer) return self.image.frombytes(buffer)