Rename back from color to colour

All of the code base is BE, so this change was inconsistent.
This renaming direction is a bit more "dangerous" due to inadvertent
renamings of PDFium members. Hope I've captured them all.

README.md

@@ -156,26 +156,26 @@ Here are some examples of using the support model API.
   ```python
   image = page.render_to(
       # defaults
-      scale = 1,                          # 72dpi resolution
-      rotation = 0,                       # no additional rotation
-      crop = (0, 0, 0, 0),                # no crop (form: left, right, bottom, top)
-      greyscale = False,                  # coloured output
-      fill_color = (255, 255, 255, 255),  # fill bitmap with white background before rendering (form: RGBA)
-      color_scheme = None,                # no custom colour scheme
-      fill_to_stroke = False,             # don't stroke fill paths (relevant for custom colour scheme only)
-      optimise_mode = OptimiseMode.NONE,  # no optimisations (e. g. subpixel rendering)
-      draw_annots = True,                 # show annotations
-      draw_forms = True,                  # show forms
-      no_smoothtext = False,              # anti-alias text
-      no_smoothimage = False,             # anti-alias images
-      no_smoothpath = False,              # anti-alias paths
-      force_halftone = False,             # don't force halftone for image stretching
-      rev_byteorder = False,              # don't reverse byte order
-      prefer_bgrx = False,                # don't prefer four channels for coloured output
-      force_bitmap_format = None,         # don't force a specific bitmap format
-      extra_flags = 0,                    # no extra flags
-      allocator = None,                   # no custom allocator
-      memory_limit = 2**30,               # maximum allocation (1 GiB)
+      scale = 1,                           # 72dpi resolution
+      rotation = 0,                        # no additional rotation
+      crop = (0, 0, 0, 0),                 # no crop (form: left, right, bottom, top)
+      greyscale = False,                   # coloured output
+      fill_colour = (255, 255, 255, 255),  # fill bitmap with white background before rendering (form: RGBA)
+      colour_scheme = None,                # no custom colour scheme
+      fill_to_stroke = False,              # don't stroke fill paths (relevant for custom colour scheme only)
+      optimise_mode = OptimiseMode.NONE,   # no optimisations (e. g. subpixel rendering)
+      draw_annots = True,                  # show annotations
+      draw_forms = True,                   # show forms
+      no_smoothtext = False,               # anti-alias text
+      no_smoothimage = False,              # anti-alias images
+      no_smoothpath = False,               # anti-alias paths
+      force_halftone = False,              # don't force halftone for image stretching
+      rev_byteorder = False,               # don't reverse byte order
+      prefer_bgrx = False,                 # don't prefer four channels for coloured output
+      force_bitmap_format = None,          # don't force a specific bitmap format
+      extra_flags = 0,                     # no extra flags
+      allocator = None,                    # no custom allocator
+      memory_limit = 2**30,                # maximum allocation (1 GiB)
   )
   image.show()
   image.close()
@@ -510,7 +510,7 @@ Nonetheless, the following guide may be helpful to get started with the raw API,
   
   [^ctypes_no_oor]: Confer the [ctypes documentation on Pointers](https://docs.python.org/3/library/ctypes.html#pointers).
 
-* Finally, let's finish this guide with an example on how to render the first page of a document to a `PIL` image in `RGBA` color format.
+* Finally, let's finish this guide with an example on how to render the first page of a document to a `PIL` image in `RGBA` colour format.
   ```python
   import math
   import ctypes
@@ -535,7 +535,7 @@ Nonetheless, the following guide may be helpful to get started with the raw API,
   use_alpha = False  # We don't render with transparent background
   bitmap = pdfium.FPDFBitmap_Create(width, height, int(use_alpha))
   # Fill the whole bitmap with a white background
-  # The color is given as a 32-bit integer in ARGB format (8 bits per channel)
+  # The colour is given as a 32-bit integer in ARGB format (8 bits per channel)
   pdfium.FPDFBitmap_FillRect(bitmap, 0, 0, width, height, 0xFFFFFFFF)
   
   # Store common rendering arguments

docs/devel/changelog_staging.md

@@ -16,14 +16,14 @@
     - PDFium is now provided with an external, python-allocated buffer for rendering. This has numerous advantages, most notably that callers don't need to free resources anymore. `PdfPage.render_base()` now directly returns a ctypes ubyte array; `BitmapDataHolder` has been removed.
     - Changed rendering parameters
         - `annotations` was renamed to `draw_annots`
-        - `colour` was renamed to `color` and now only takes a list of 4 values for simplicity - it may not be 3 values or `None` anymore
+        - `colour` was renamed to `fill_colour` and now only takes a list of 4 values for simplicity - it may not be 3 values or `None` anymore
         - `no_antialias` has been replaced with separate boolean options `no_smoothtext`, `no_smoothimage`, and `no_smoothpath`
 
     *Other changes*
     - `OutlineItem` now contains information on the number of sub-items (`n_kids` attribute).
     - All document-level methods that take a page index now accept negative values for reverse indexing (except the rendering methods).
     - New method `PdfDocument.get_page_size()` to retrieve page size by index without needing to load a `PdfPage` (uses `FPDF_GetPageSizeByIndexF()` under the hood).
-    - New rendering parameters added: `color_scheme`, `fill_to_stroke`, `force_halftone`, `draw_forms`, `rev_byteorder`, `prefer_bgrx`, `force_bitmap_format`, `extra_flags`, `allocator`, and `memory_limit`.
+    - New rendering parameters added: `colour_scheme`, `fill_to_stroke`, `force_halftone`, `draw_forms`, `rev_byteorder`, `prefer_bgrx`, `force_bitmap_format`, `extra_flags`, `allocator`, and `memory_limit`.
     - Added new `render_to()` functions to `PdfPage` and `PdfDocument` that take a custom bitmap converter, to transform the ctypes array to a different object. A set of built-in converters is provided with the `BitmapConv` class. Confer the updated API documentation for details. The previous rendering functions (`render_topil()` `render_tobytes()`, ...) are still around as deprecated aliases but might be removed eventually.
     - New rendering target `numpy_ndarray` added.
     - The `pil_image` rendering target now accepts a `prefer_la` parameter to request automatic conversion of `BGRA`/`RGBA` to `LA` if rendering in greyscale mode with alpha channel.

docs/devel/tasks.md

@@ -45,7 +45,7 @@ Also see the issues panel and inline `TODO` marks in source code.
 
 ### Miscellaneous
 * Ask Linux distributors to package PDFium.
-* Discuss rendering methods in PDFium's mailing list (we'd like a way to combine matrix, color scheme and interruptibility).
+* Discuss rendering methods in PDFium's mailing list (we'd like a way to combine matrix, colour scheme and interruptibility).
 * Add means to plug in PDFium headers/binaries from an arbitrary location, probably using custom environment variables.
 * Keep in mind that `ctypes.pythonapi` exists. Maybe we could replace our wonky `id()` based keep-the-object-alive approach with proper incref/decref calls?
 * Find out if/when we need to use `ctypes.byref()`.

docs/source/changelog.md

@@ -76,7 +76,7 @@
 - Updated PDFium from `5145` to `5159` (autorelease).
 - Subtle improvements were applied to the handling of input buffers (providing `read()` beside `readinto()` is now explicitly required).
 - Concerning file access, the autoclose logic has been moved from the loder data holder to `PdfDocument.close()`, which is somewhat more obvious.
-- The internal `color_tohex()` utility function has been optimised by using bit-shifts and the binary `or` operator.
+- The internal `colour_tohex()` utility function has been optimised by using bit-shifts and the binary `or` operator.
 - Disabled implicit source build in `setup.py`, which used to be the fallback if no pre-built binaries are available for the host platform. Now, an exception is raised instead.
 - The changelog is now better integrated with automatic releases.
 - In the release workflow, reverted an inelegant change regarding dependency installation order.
@@ -251,7 +251,7 @@
   * Restructured rendering functions to provide multiple different output types:
     `render_page_topil()` and `render_page_tobytes()` replace `render_page()`; similarly, `render_pdf_topil()` and `render_pdf_tobytes()` replace `render_pdf()`.
     These functions are derived from `render_page_base()` and `render_pdf_base()`, respectively.
-  * In `render_page_...()` and `render_pdf_...()`, we now only accept RGBA tuples for the color parameter.
+  * In `render_page_...()` and `render_pdf_...()`, we now only accept RGBA tuples for the colour parameter.
 - The Pillow dependency is now optional in the core library.
 - Removed workarounds for non-ascii filepaths on Windows. The issues with `FPDF_LoadDocument()` should be fixed since PDFium `4915`. Thanks to Lei Zhang and Thomas Sepez of PDFium team.
 - Added some boilerplate code to setup scripts to make sure imports always work when the file is invoked directly.
@@ -302,7 +302,7 @@
 ## 0.13.0 (2022-02-14)
 
 - Updated PDFium from `4874` to `4888`.
-- In `render_page()`, the bitmap is now directly initialised with the right color format, rather than always using RGBA and converting afterwards. This is expected to improve performance when rendering without alpha channel, in particular for greyscale.
+- In `render_page()`, the bitmap is now directly initialised with the right colour format, rather than always using RGBA and converting afterwards. This is expected to improve performance when rendering without alpha channel, in particular for greyscale.
 - Installed a new support model class `PdfDocument` on top of the separate helper functions, for object oriented document access. This should be easier to use and more like the API of other Python PDF libraries.
 - Fixed `setup.py` to always call `getdeps` first, before other imports that already require packages that `getdeps` should install.
 - Restructured platform-specific setup to greatly reduce code duplication.

src/pypdfium2/_cli/render.py

@@ -12,7 +12,7 @@
 from pypdfium2._cli._parsers import pagetext_type
 
 
-ColorOpts = dict(
+ColourOpts = dict(
     metavar = "C",
     nargs = 4,
     type = int,
@@ -65,10 +65,10 @@ def attach_parser(subparsers):
         help = "Rotate pages by 90, 180 or 270 degrees",
     )
     parser.add_argument(
-        "--fill-color",
+        "--fill-colour",
         default = (255, 255, 255, 255),
-        help = "Color the bitmap will be filled with before rendering. It shall be given in RGBA format as a sequence of integers ranging from 0 to 255. Defaults to white.",
-        **ColorOpts,
+        help = "Colour the bitmap will be filled with before rendering. It shall be given in RGBA format as a sequence of integers ranging from 0 to 255. Defaults to white.",
+        **ColourOpts,
     )
     parser.add_argument(
         "--force-halftone",
@@ -94,7 +94,7 @@ def attach_parser(subparsers):
     parser.add_argument(
         "--greyscale",
         action = "store_true",
-        help = "Whether to render in greyscale mode (no colors)",
+        help = "Whether to render in greyscale mode (no colours)",
     )
     parser.add_argument(
         "--crop",
@@ -127,30 +127,30 @@ def attach_parser(subparsers):
         help = "The number of processes to use for rendering (defaults to the number of CPU cores)",
     )
 
-    color_scheme = parser.add_argument_group(
-        title = "Color scheme",
-        description = "Options for rendering with custom color scheme",
+    colour_scheme = parser.add_argument_group(
+        title = "Colour scheme",
+        description = "Options for rendering with custom colour scheme",
     )
-    color_scheme.add_argument(
+    colour_scheme.add_argument(
         "--path-fill",
-        **ColorOpts
+        **ColourOpts
     )
-    color_scheme.add_argument(
+    colour_scheme.add_argument(
         "--path-stroke",
-        **ColorOpts
+        **ColourOpts
     )
-    color_scheme.add_argument(
+    colour_scheme.add_argument(
         "--text-fill",
-        **ColorOpts
+        **ColourOpts
     )
-    color_scheme.add_argument(
+    colour_scheme.add_argument(
         "--text-stroke",
-        **ColorOpts
+        **ColourOpts
     )
-    color_scheme.add_argument(
+    colour_scheme.add_argument(
         "--fill-to-stroke",
         action = "store_true",
-        help = "Whether fill paths need to be stroked. Ignored if not rendering with custom color scheme.",
+        help = "Whether fill paths need to be stroked. Ignored if not rendering with custom colour scheme.",
     )
 
 
@@ -175,12 +175,12 @@ def main(args):
         )
         cs = None
         if all(cs_kwargs.values()):
-            cs = pdfium.ColorScheme(
+            cs = pdfium.ColourScheme(
                 fill_to_stroke = args.fill_to_stroke,
                 **cs_kwargs,
             )
         elif any(cs_kwargs.values()):
-            raise ValueError("If rendering with custom color scheme, all parameters need to be set explicitly.")
+            raise ValueError("If rendering with custom colour scheme, all parameters need to be set explicitly.")
 
         kwargs = dict(
             page_indices = page_indices,
@@ -189,8 +189,8 @@ def main(args):
             rotation = args.rotation,
             crop = args.crop,
             greyscale = args.greyscale,
-            fill_color = args.fill_color,
-            color_scheme = cs,
+            fill_colour = args.fill_colour,
+            colour_scheme = cs,
             optimise_mode = args.optimise_mode,
             draw_annots = not args.no_annotations,
             draw_forms = not args.no_forms,

src/pypdfium2/_helpers/_utils.py

@@ -4,20 +4,20 @@
 import pypdfium2._pypdfium as pdfium
 
 
-def validate_colors(bg_color, color_scheme):
-    colors = [bg_color]
-    if color_scheme is not None:
-        colors += list( color_scheme.colors.values() )
-    for col in colors:
+def validate_colours(bg_colour, colour_scheme):
+    colours = [bg_colour]
+    if colour_scheme is not None:
+        colours += list( colour_scheme.colours.values() )
+    for col in colours:
         if len(col) != 4:
-            raise ValueError("Color must consist of exactly 4 values.")
+            raise ValueError("Colour must consist of exactly 4 values.")
         if not all(0 <= c <= 255 for c in col):
-            raise ValueError("Color value exceeds boundaries.")
+            raise ValueError("Colour value exceeds boundaries.")
 
 
-def auto_bitmap_format(bg_color, greyscale, prefer_bgrx):
-    # no need to take alpha values of color_scheme into account (drawings are additive)
-    if (bg_color[3] < 255):
+def auto_bitmap_format(bg_colour, greyscale, prefer_bgrx):
+    # no need to take alpha values of colour_scheme into account (drawings are additive)
+    if (bg_colour[3] < 255):
         return pdfium.FPDFBitmap_BGRA
     elif greyscale:
         return pdfium.FPDFBitmap_Gray
@@ -27,27 +27,27 @@ def auto_bitmap_format(bg_color, greyscale, prefer_bgrx):
         return pdfium.FPDFBitmap_BGR
 
 
-def color_tohex(color, rev_byteorder):
+def colour_tohex(colour, rev_byteorder):
     """
-    Convert an RGBA color specified by 4 integers ranging from 0 to 255 to a single 32-bit integer as required by PDFium.
+    Convert an RGBA colour specified by 4 integers ranging from 0 to 255 to a single 32-bit integer as required by PDFium.
     If using regular byte order, the output format will be ARGB. If using reversed byte order, it will be ABGR.
     """
 
-    r, g, b, a = color
+    r, g, b, a = colour
 
-    # color is interpreted differently with FPDF_REVERSE_BYTE_ORDER (perhaps inadvertently?)
+    # colour is interpreted differently with FPDF_REVERSE_BYTE_ORDER (perhaps inadvertently?)
     if rev_byteorder:
         channels = (a, b, g, r)
     else:
         channels = (a, r, g, b)
 
-    c_color = 0
+    c_colour = 0
     shift = 24
     for c in channels:
-        c_color |= c << shift
+        c_colour |= c << shift
         shift -= 8
 
-    return c_color
+    return c_colour
 
 
 def get_functype(struct, funcname):

src/pypdfium2/_helpers/converters.py

@@ -38,7 +38,7 @@ def run(result, renderer_kws, *args, **kwargs):
         
         Parameters:
             result (tuple):
-                Result of the :meth:`.PdfPage.render_base` call (ctypes array, color format, size).
+                Result of the :meth:`.PdfPage.render_base` call (ctypes array, colour format, size).
             renderer_kws (dict):
                 Dictionary of keywords that were passed to :meth:`.PdfPage.render_base` by the caller. May be empty.
             args (tuple):
@@ -72,7 +72,7 @@ class any (BitmapConvBase):
                 It could be a function, a class with constructor, or an instance of a class implementing ``__call__``.
         Returns:
             (typing.Any, ...):
-                The converted rendering result (implementation-specific), and additional information returned by :meth:`.PdfPage.render_base` (color format, size).
+                The converted rendering result (implementation-specific), and additional information returned by :meth:`.PdfPage.render_base` (colour format, size).
         """
 
         @staticmethod
@@ -89,7 +89,7 @@ class numpy_ndarray (BitmapConvBase):
         This converter never makes a copy of the data.
         
         Returns:
-            (numpy.ndarray, str): NumPy array, and color format.
+            (numpy.ndarray, str): NumPy array, and colour format.
         """
 
         @staticmethod
@@ -122,7 +122,7 @@ class pil_image (BitmapConvBase):
         
         Hint:
             This uses :func:`PIL.Image.frombuffer` under the hood.
-            If possible for the color format in question, the image will reference the ctypes array. Otherwise, PIL may create a copy of the data.
+            If possible for the colour format in question, the image will reference the ctypes array. Otherwise, PIL may create a copy of the data.
             At the time of writing, PIL can directly work with ``RGBA``, ``RGBX`` or ``L`` pixel data.
             Depending on the use case, you may want to consider setting the rendering parameters *rev_byteorder* and *prefer_bgrx* to :data:`True`
             to generate natively compatible output.
@@ -131,7 +131,7 @@ class pil_image (BitmapConvBase):
         @staticmethod
         def run(result, renderer_kws, prefer_la=False):
 
-            # NOTE This converter does not return additional parameters, as information on size and color format (mode) is already contained in the image object.
+            # NOTE This converter does not return additional parameters, as information on size and colour format (mode) is already contained in the image object.
 
             if PIL is None:
                 raise RuntimeError("Pillow library needs to be installed for pil_image() converter.")