Image.new(): correct docstring and comment about uninitialized memory - #9960
Merged
Conversation
The comment "# don't initialize" and the docstring's claim that passing `None` as the fill color leaves the image uninitialized have both been untrue for a long time. dcd40ce (python-pillow#348, Pillow 2.2.0) added a memset to the block-allocation path, to fix python-pillow#254 (uninitialized memory showing through in image transformations); that memset later became a calloc in 52d60cd. Since the block allocator was used for everything up to THRESHOLD (16 MiB), only very large images were still uninitialized after that. 768936f (python-pillow#1781, Pillow 3.3.0) turned the array-allocation path's per-line mallocs into callocs, which is the point where no allocation path could return dirty memory any more. 7a1e70d (python-pillow#2655, Pillow 4.3.0) added an explicit internal ImagingNewDirty for callers that overwrite the whole image anyway, and 0a3c852 (python-pillow#2738) added the block pool, where a caller asks for either a cleared or a dirty block. Nothing exposed to Python returns an image whose memory is left dirty: core.new() uses ImagingNew (cleared), and core.fill() uses ImagingNewDirty but immediately fills it.
radarhere
approved these changes
Sep 4, 2026
radarhere
reviewed
Sep 5, 2026
| creating RGB or HSV images, you can also use color strings as supported | ||
| by the ImageColor module. See :ref:`colors` for more information. If the | ||
| color is None, the image is not initialised. | ||
| color is None, the image is filled with zeroes. |
Member
There was a problem hiding this comment.
Suggested change
| color is None, the image is filled with zeroes. | |
| color is ``None``, the image is black. |
What do you think of this? I expect users reading the documentation are more concerned with the visual result than the underlying data.
Contributor
Author
There was a problem hiding this comment.
Fine by me, but does that stand for a CMYK image?
Member
There was a problem hiding this comment.
I've created akx#24 to say
The default color is zero, which appears as black in single band or RGB-based images.
Noneis also treated as zero.
Co-authored-by: Andrew Murray <radarhere@users.noreply.github.com>
Contributor
Author
|
I was slightly surprised that |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The comment "# don't initialize" and the docstring's claim that passing
Noneas the fill color leaves the image uninitialized have both been untrue for a long time.dcd40ce (#348, Pillow 2.2.0) added a memset to the block-allocation path, to fix #254 (uninitialized memory showing through in image transformations); that memset later became a calloc in 52d60cd. Since the block allocator was used for everything up to THRESHOLD (16 MiB), only very large images were still uninitialized after that. 768936f (#1781, Pillow 3.3.0) turned the array-allocation path's per-line mallocs into callocs, which is the point where no allocation path could return dirty memory any more.
7a1e70d (#2655, Pillow 4.3.0) added an explicit internal ImagingNewDirty for callers that overwrite the whole image anyway, and 0a3c852 (#2738) added the block pool, where a caller asks for either a cleared or a dirty block.
Nothing exposed to Python returns an image whose memory is left dirty: core.new() uses ImagingNew (cleared), and core.fill() uses ImagingNewDirty but immediately fills it.
Follows up on #9957.