Rename drawing areas to cells

README.rst

@@ -56,11 +56,11 @@ As a command line tool
     picture layout options:
       -l, --layout LAYOUT   specify grid layout (columns x rows) of pictures on
                             page, e.g. 2x3 or 2,3; default is 1x1
-      -m, --margin MARGIN   set width of empty space around drawing areas; default
-                            is 72 (72 points = 1 inch)
-      -s, --stretch-small   scale small pictures up to fit drawing areas
-      -a, --fill-area       fill drawing areas with pictures, ignoring the
-                            pictures' aspect ratio
+      -m, --margin MARGIN   set width of empty space around the cells containing
+                            pictures; default is 72 (72 points = 1 inch)
+      -s, --stretch-small   scale small pictures up to fit cells
+      -c, --fill-cell       fill cells with pictures, ignoring the pictures'
+                            aspect ratio
 
 
 Examples
@@ -132,7 +132,7 @@ and their default values correspond to the above shown command line options:
         layout=(1, 1),
         margin=72,
         stretch_small=False,
-        fill_area=False,
+        fill_cell=False,
     )
 
 
@@ -166,7 +166,7 @@ their default values correspond to the above shown command line options:
         layout=(1, 1),
         margin=72,
         stretch_small=False,
-        fill_area=False,
+        fill_cell=False,
     )
 
 

changelog.d/20241015_095444_michalportes1_cell_box.md

@@ -0,0 +1,41 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+<!--
+### Removed
+
+- A bullet item for the Removed category.
+
+-->
+<!--
+### Added
+
+- A bullet item for the Added category.
+
+-->
+### Breaking changes
+
+- Library API: `fill_area` keyword parameters renamed to `fill_cell`
+- CLI: the `-a`/`--fill-area` option renamed to `-c`/`--fill-cell`
+
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category.
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category.
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category.
+
+-->

src/pictureshow/cli.py

@@ -117,20 +117,20 @@ def _setup_parser():
         '--margin',
         type=float,
         default=72,
-        help='set width of empty space around drawing areas; '
+        help='set width of empty space around the cells containing pictures; '
              'default is %(default)s (72 points = 1 inch)',
     )
     picture_group.add_argument(
         '-s',
         '--stretch-small',
         action='store_true',
-        help='scale small pictures up to fit drawing areas',
+        help='scale small pictures up to fit cells',
     )
     picture_group.add_argument(
-        '-a',
-        '--fill-area',
+        '-c',
+        '--fill-cell',
         action='store_true',
-        help="fill drawing areas with pictures, ignoring the pictures' aspect ratio",
+        help="fill cells with pictures, ignoring the pictures' aspect ratio",
     )
 
     return parser
@@ -193,7 +193,7 @@ def main(argv=None):
                     layout=args.layout,
                     margin=args.margin,
                     stretch_small=args.stretch_small,
-                    fill_area=args.fill_area,
+                    fill_cell=args.fill_cell,
             ):
                 print('.' if ok_flag else '!', end='', flush=True)
             print()

src/pictureshow/core.py

@@ -18,7 +18,7 @@
 
 DELIMITER = re.compile('[x,]')
 
-_Area = namedtuple('_Area', 'x y width height')
+_Box = namedtuple('_Box', 'x y width height')
 
 _Result = namedtuple('_Result', 'num_ok errors num_pages')
 
@@ -39,7 +39,7 @@ def save_pdf(
             layout=(1, 1),
             margin=72,
             stretch_small=False,
-            fill_area=False,
+            fill_cell=False,
     ):
         """Save pictures stored in `self._pic_files` to a PDF document.
 
@@ -57,7 +57,7 @@ def save_pdf(
                 layout=layout,
                 margin=margin,
                 stretch_small=stretch_small,
-                fill_area=fill_area,
+                fill_cell=fill_cell,
         ):
             pass
         return self.result
@@ -73,7 +73,7 @@ def _save_pdf(
             layout,
             margin,
             stretch_small,
-            fill_area,
+            fill_cell,
     ):
         output_file = self._validate_target_path(output_file, force_overwrite)
         page_size = self._validate_page_size(page_size, landscape)
@@ -83,9 +83,9 @@ def _save_pdf(
         self._backend.init(output_file, page_size, bg_color)
         valid_pics = self._valid_pictures()
         self.num_ok = 0
-        areas = tuple(self._areas(layout, page_size, margin))
+        cells = tuple(self._cells(layout, page_size, margin))
         while True:
-            for area in areas:
+            for cell in cells:
                 try:
                     while True:
                         picture = next(valid_pics)
@@ -99,12 +99,12 @@ def _save_pdf(
                     return
                 x, y, *pic_size = self._position_and_size(
                     self._backend.get_picture_size(picture),
-                    area[2:],    # short for (area.width, area.height)
+                    (cell.width, cell.height),
                     stretch_small,
-                    fill_area,
+                    fill_cell,
                 )
                 self._backend.add_picture(
-                    picture, (area.x + x, area.y + y), pic_size
+                    picture, (cell.x + x, cell.y + y), pic_size
                 )
                 self.num_ok += 1
                 yield True
@@ -184,49 +184,49 @@ def _valid_pictures(self):
                 yield picture
 
     @staticmethod
-    def _position_and_size(pic_size, area_size, stretch_small, fill_area):
-        """Calculate position and size of the picture in the area."""
-        area_width, area_height = area_size
-        if fill_area:
-            return 0, 0, area_width, area_height
+    def _position_and_size(pic_size, cell_size, stretch_small, fill_cell):
+        """Calculate position and size of the picture within the cell."""
+        cell_width, cell_height = cell_size
+        if fill_cell:
+            return 0, 0, cell_width, cell_height
 
         pic_width, pic_height = pic_size
-        pic_is_big = pic_width > area_width or pic_height > area_height
+        pic_is_big = pic_width > cell_width or pic_height > cell_height
 
-        # calculate scale factor to fit picture to area
+        # calculate scale factor to fit picture to cell
         if pic_is_big or stretch_small:
-            pic_is_wide = pic_width / pic_height > area_width / area_height
-            scale = area_width / pic_width if pic_is_wide else area_height / pic_height
+            pic_is_wide = pic_width / pic_height > cell_width / cell_height
+            scale = cell_width / pic_width if pic_is_wide else cell_height / pic_height
             pic_width *= scale
             pic_height *= scale
 
-        # center picture to area
-        x = (area_width - pic_width) / 2
-        y = (area_height - pic_height) / 2
+        # center picture in cell
+        x = (cell_width - pic_width) / 2
+        y = (cell_height - pic_height) / 2
 
         return x, y, pic_width, pic_height
 
     @staticmethod
-    def _areas(layout, page_size, margin):
+    def _cells(layout, page_size, margin):
         num_columns, num_rows = layout
         page_width, page_height = page_size
 
-        area_width = (page_width - (num_columns + 1) * margin) / num_columns
-        area_height = (page_height - (num_rows + 1) * margin) / num_rows
-        if area_width < 1 or area_height < 1:
+        cell_width = (page_width - (num_columns + 1) * margin) / num_columns
+        cell_height = (page_height - (num_rows + 1) * margin) / num_rows
+        if cell_width < 1 or cell_height < 1:
             raise MarginError(f'margin value too high: {margin}')
 
-        areas_y_coords = (
-            page_height - row * (area_height + margin)
+        cells_y_coords = (
+            page_height - row * (cell_height + margin)
             for row in range(1, num_rows + 1)
         )
-        areas_x_coords = (
-            margin + col * (area_width + margin)
+        cells_x_coords = (
+            margin + col * (cell_width + margin)
             for col in range(num_columns)
         )
-        # yield areas row-wise
-        for y, x in itertools.product(areas_y_coords, areas_x_coords):
-            yield _Area(x, y, area_width, area_height)
+        # yield cells row-wise
+        for y, x in itertools.product(cells_y_coords, cells_x_coords):
+            yield _Box(x, y, cell_width, cell_height)
 
 
 def pictures_to_pdf(
@@ -239,7 +239,7 @@ def pictures_to_pdf(
         layout=(1, 1),
         margin=72,
         stretch_small=False,
-        fill_area=False,
+        fill_cell=False,
 ):
     """Save one or more pictures to a PDF document.
 
@@ -259,5 +259,5 @@ def pictures_to_pdf(
         layout=layout,
         margin=margin,
         stretch_small=stretch_small,
-        fill_area=fill_area,
+        fill_cell=fill_cell,
     )

tests/test_pictures_to_pdf.py

@@ -173,8 +173,8 @@ def test_stretch_small(new_pdf):
     assert_pdf(new_pdf, 1)
 
 
-def test_fill_area(new_pdf):
-    result = pictures_to_pdf(PIC_FILE, output_file=new_pdf, fill_area=True)
+def test_fill_cell(new_pdf):
+    result = pictures_to_pdf(PIC_FILE, output_file=new_pdf, fill_cell=True)
 
     assert result == (1, [], 1)
     assert_pdf(new_pdf, 1)