add helper method Drawing.page_setup()

Author: mozman

docs/source/drawing/drawing.rst

@@ -196,6 +196,8 @@ Drawing Object
 
     .. automethod:: new_layout
 
+    .. automethod:: page_setup
+
     .. automethod:: delete_layout
 
     .. automethod:: add_image_def

integration_tests/test_document_page_setup.py

@@ -0,0 +1,59 @@
+#  Copyright (c) 2022, Manfred Moitzi
+#  License: MIT License
+
+import pytest
+import ezdxf
+
+
+def test_reset_layout1_landscape():
+    doc = ezdxf.new()
+    assert len(doc.layouts) == 2
+    psp = doc.page_setup("Layout1", fmt="ISO A0")
+    assert len(doc.layouts) == 2
+    assert psp.dxf_layout.dxf.paper_width == 1189
+    assert psp.dxf_layout.dxf.paper_height == 841
+
+
+def test_invalid_paper_format_returns_A3():
+    doc = ezdxf.new()
+    with pytest.raises(ValueError):
+        doc.page_setup("Layout1", fmt="INVALID")
+
+
+def test_reset_layout1_portrait():
+    doc = ezdxf.new()
+    assert len(doc.layouts) == 2
+    psp = doc.page_setup("Layout1", fmt="ISO A0", landscape=False)
+    assert len(doc.layouts) == 2
+    assert psp.dxf_layout.dxf.paper_width == 841
+    assert psp.dxf_layout.dxf.paper_height == 1189
+
+
+def test_resetting_layout1_creates_a_new_main_viewport():
+    doc = ezdxf.new()
+    psp = doc.paperspace("Layout1")
+    assert len(psp) == 0  # no main viewport exist, not required
+    psp = doc.page_setup("Layout1", fmt="ISO A0")
+    assert len(psp.query("VIEWPORT")) == 1
+
+
+def test_resetting_layout1_does_not_delete_entities():
+    doc = ezdxf.new()
+    psp = doc.paperspace("Layout1")
+    psp.add_point((0, 0))
+    assert len(psp) == 1
+    psp = doc.page_setup("Layout1", fmt="ISO A0")
+    assert len(psp.query("POINT")) == 1
+
+
+def test_new_layout2():
+    doc = ezdxf.new()
+    assert len(doc.layouts) == 2
+    psp = doc.page_setup("Layout2", fmt="ISO A0")
+    assert len(doc.layouts) == 3
+    assert psp.dxf_layout.dxf.paper_width == 1189
+    assert psp.dxf_layout.dxf.paper_height == 841
+
+
+if __name__ == '__main__':
+    pytest.main([__file__])

src/ezdxf/document.py

@@ -819,9 +819,7 @@ def paperspace(self, name: str = "") -> Paperspace:
             psp = self.layouts.get(name)
             if isinstance(psp, Paperspace):
                 return psp
-            raise KeyError(
-                "use method modelspace() to acquire the modelspace."
-            )
+            raise KeyError("use method modelspace() to acquire the modelspace.")
         else:
             return self.active_layout()
 
@@ -913,7 +911,7 @@ def delete_layout(self, name: str) -> None:
         """
         Delete paper space layout `name` and all entities owned by this layout.
         Available only for DXF R2000 or later, DXF R12 supports only one
-        paperspace and it can't be deleted.
+        paperspace, and it can't be deleted.
 
         """
         if name not in self.layouts:
@@ -942,6 +940,68 @@ def new_layout(self, name, dxfattribs=None) -> "Layout":
         else:
             return self.layouts.new(name, dxfattribs)
 
+    def page_setup(
+        self,
+        name: str = "Layout1",
+        fmt: str = "ISO A3",
+        landscape=True,
+    ) -> Paperspace:
+        """
+        Creates a new paperspace layout if `name` does not
+        exist or reset the existing layout.
+        The paper format name `fmt` defines one of the following paper sizes,
+        measures in landscape orientation:
+
+        =========== ======= ======= =======
+        Name        Units   Width   Height
+        =========== ======= ======= =======
+        ISO A0      mm      1189    841
+        ISO A1      mm      841     594
+        ISO A2      mm      594     420
+        ISO A3      mm      420     297
+        ISO A4      mm      297     210
+        ANSI A      inch    11      8.5
+        ANSI B      inch    17      11
+        ANSI C      inch    22      17
+        ANSI D      inch    34      22
+        ANSI E      inch    44      34
+        ARCH C      inch    24      18
+        ARCH D      inch    36      24
+        ARCH E      inch    48      36
+        ARCH E1     inch    42      30
+        Letter      inch    11      8.5
+        Legal       inch    14      8.5
+        =========== ======= ======= =======
+
+        The layout uses the associated units of the paper format as drawing
+        units, has no margins or offset defined and the scale of the paperspace
+        layout is 1:1.
+
+        Args:
+            name: paperspace layout name
+            fmt: paper format
+            landscape: ``True`` for landscape orientation, ``False`` for portrait
+                orientation
+
+        """
+        from ezdxf.tools.standards import PAGE_SIZES
+
+        width: float
+        height: float
+        try:
+            units, width, height = PAGE_SIZES[fmt]
+        except KeyError:
+            raise ValueError(f"unknown paper format: {fmt}")
+        if not landscape:
+            width, height = height, width
+        try:
+            psp = self.paperspace(name)
+        except KeyError:
+            psp = cast(Paperspace, self.new_layout(name))
+
+        psp.page_setup(size=(width, height), margins=(0, 0, 0, 0), units=units)
+        return psp
+
     def acquire_arrow(self, name: str):
         """For standard AutoCAD and ezdxf arrows create block definitions if
         required, otherwise check if block `name` exist. (internal API)

src/ezdxf/tools/standards.py

@@ -1,5 +1,6 @@
 # Copyright (c) 2016-2022, Manfred Moitzi
 # License: MIT License
+from __future__ import annotations
 from typing import TYPE_CHECKING, List, Tuple, Sequence, Union, cast
 
 from ezdxf import const
@@ -11,13 +12,15 @@
 import logging
 
 if TYPE_CHECKING:
-    from ezdxf.eztypes import Drawing, DimStyle
+    from ezdxf.document import Drawing
+    from ezdxf.entities import DimStyle
+    from ezdxf.layouts import Paperspace
 
 logger = logging.getLogger("ezdxf")
 LTypeDef = Tuple[str, str, Sequence[float]]
 
 
-def setup_drawing(doc: "Drawing", topics: Union[str, bool, Sequence] = "all"):
+def setup_drawing(doc: Drawing, topics: Union[str, bool, Sequence] = "all"):
     """
     Setup default linetypes, text styles or dimension styles.
 
@@ -69,7 +72,7 @@ def get_token(name: str) -> List[str]:
         setup_dimstyles(doc, domain=domain)
 
 
-def setup_linetypes(doc: "Drawing") -> None:
+def setup_linetypes(doc: Drawing) -> None:
     measurement = 1
     if doc:
         measurement = doc.header.get("$MEASUREMENT", measurement)
@@ -86,7 +89,7 @@ def setup_linetypes(doc: "Drawing") -> None:
         )
 
 
-def setup_styles(doc: "Drawing") -> None:
+def setup_styles(doc: Drawing) -> None:
     doc.header["$TEXTSTYLE"] = "OpenSans"
     for name, font in styles():
         if name in doc.styles:
@@ -99,7 +102,7 @@ def setup_styles(doc: "Drawing") -> None:
         )
 
 
-def setup_dimstyles(doc: "Drawing", domain: str = "all") -> None:
+def setup_dimstyles(doc: Drawing, domain: str = "all") -> None:
     setup_styles(doc)
     ezdxf_dimstyle = setup_dimstyle(
         doc,
@@ -3976,3 +3979,23 @@ def setup_visual_styles_r2013(doc: "Drawing"):
         ),
     },
 }
+
+# all page sizes in landscape orientation
+PAGE_SIZES = {
+    "ISO A0": ("mm", 1189, 841),
+    "ISO A1": ("mm", 841, 594),
+    "ISO A2": ("mm", 594, 420),
+    "ISO A3": ("mm", 420, 297),
+    "ISO A4": ("mm", 297, 210),
+    "ANSI A": ("inch", 11, 8.5),
+    "ANSI B": ("inch", 17, 11),
+    "ANSI C": ("inch", 22, 17),
+    "ANSI D": ("inch", 34, 22),
+    "ANSI E": ("inch", 44, 34),
+    "ARCH C": ("inch", 24, 18),
+    "ARCH D": ("inch", 36, 24),
+    "ARCH E": ("inch", 48, 36),
+    "ARCH E1": ("inch", 42, 30),
+    "Letter": ("inch", 11, 8.5),
+    "Legal": ("inch", 14, 8.5),
+}