pytecplot 1.5.2__py3-none-any.whl

tecplot/text/label_format.py

@@ -0,0 +1,374 @@
+from builtins import int, str, super
+
+from ..tecutil import _tecutil
+from ..constant import *
+from ..exception import *
+from ..tecutil import Index, StringList, flatten_args, lock, sv
+from .. import session
+
+
+class LabelFormat(session.Style):
+    """Formatting of numbers shown along in axes and in legends.
+
+    This example shows how to format tick label along an axis:
+
+    .. code-block:: python
+        :emphasize-lines: 31-36
+
+        from datetime import datetime
+        import tecplot as tp
+        from tecplot.constant import PlotType, AxisMode, AxisAlignment, NumberFormat
+
+        tp.new_layout()
+        plot = tp.active_frame().plot(tp.constant.PlotType.Sketch)
+        plot.activate()
+
+        # setup the plot area margins
+        plot.axes.viewport.left = 10
+        plot.axes.viewport.right = 90
+
+        # show the x-axis, set the title, and alignment with the viewport
+        xaxis = plot.axes.x_axis
+        xaxis.show = True
+        xaxis.title.text = 'Negative numbers in parentheses'
+        xaxis.title.offset = 20
+        xaxis.line.alignment = AxisAlignment.WithViewport
+        xaxis.line.position = 50
+
+        # set limits, tick placement and tick label properties
+        xaxis.ticks.auto_spacing = False
+        xaxis.min, xaxis.max = -5.123e-5, 5.234e-5
+        xaxis.ticks.spacing = (xaxis.max - xaxis.min) / 6
+        xaxis.ticks.spacing_anchor = 0
+        xaxis.tick_labels.angle = 45
+        xaxis.tick_labels.offset = 3
+
+        # format the tick labels in superscript form. example: 1.234x10^5
+        # format negative numbers to use parentheses instead of a negative sign
+        xformat = xaxis.tick_labels.format
+        xformat.format_type = NumberFormat.SuperScript
+        xformat.precision = 3
+        xformat.show_negative_sign = False
+        xformat.negative_prefix = '('
+        xformat.negative_suffix = ')'
+
+        tp.export.save_png('label_format.png', 600, supersample=3)
+
+    ..  figure:: /_static/images/label_format.png
+        :width: 300px
+        :figwidth: 300px
+    """
+    def __init__(self, labels):
+        self.labels = labels
+        super().__init__(labels._sv, sv.NUMFORMAT, **labels._kw)
+
+    @property
+    def format_type(self):
+        """`NumberFormat`: Type of number formatting to use.
+
+        Possible values: `Integer`, `FixedFloat`, `Exponential`, `BestFloat`,
+        `SuperScript`, `CustomLabel`, `LogSuperScript`, `RangeBestFloat`,
+        `DynamicLabel`, `TimeDate`.
+
+        Example usage::
+
+            >>> from tecplot.constant import NumberFormat
+            >>> axis.tick_labels.format.format_type = NumberFormat.BestFloat
+        """
+        return self._get_style(NumberFormat, sv.FORMATTING)
+
+    @format_type.setter
+    def format_type(self, value):
+        self._set_style(NumberFormat(value), sv.FORMATTING)
+
+    @property
+    def custom_labels_index(self):
+        """`Index` (zero-based): Index of the custom label to use.
+
+        Example usage::
+
+            >>> axis.tick_labels.format.custom_labels_index = 0
+        """
+        return self._get_style(Index, sv.CUSTOMLABEL)
+
+    @custom_labels_index.setter
+    def custom_labels_index(self, index):
+        index = (self.num_custom_labels + index) if index < 0 else index
+        self._set_style(Index(index), sv.CUSTOMLABEL)
+
+    @property
+    def num_custom_labels(self):
+        """`int`: Number of custom label sets available to use.
+
+        Example usage::
+
+            >>> print(axis.tick_labels.format.num_custom_labels)
+            1
+        """
+        return _tecutil.CustomLabelsGetNumSets()
+
+    def custom_labels(self, index):
+        """List of labels for custom labels for set specified by index.
+
+        Example usage::
+
+            >>> axis.tick_labels.format.custom_labels(0)
+            ['apples', 'bananas', 'carrots']
+        """
+        index = (self.num_custom_labels + index) if index < 0 else index
+        sl = _tecutil.CustomLabelsGet(index + 1)
+        ret = list(sl)
+        sl.dealloc()
+        return ret
+
+    @lock()
+    def add_custom_labels(self, *labels):
+        """Append a list of custom labels as a new set.
+
+        Example usage::
+
+            >>> labels = ['apples', 'bananas', 'carrots']
+            >>> axis.tick_labels.format.add_custom_labels(*labels)
+            >>> print(axis.tick_labels.format.custom_labels(-1))
+            ['apples', 'bananas', 'carrots']
+        """
+        with StringList(*flatten_args(labels)) as sl:
+            if not _tecutil.CustomLabelsAppend(sl):
+                raise TecplotSystemError()
+
+    @property
+    def precision(self):
+        """`int`: Number digits after decimal for fixed floating point format.
+
+        Example usage::
+
+            >>> from tecplot.constant import NumberFormat
+            >>> axis.tick_labels.format.format_type = NumberFormat.FixedFloat
+            >>> axis.tick_labels.format.precision = 3
+        """
+        return self._get_style(int, sv.PRECISION)
+
+    @precision.setter
+    def precision(self, value):
+        self._set_style(int(value), sv.PRECISION)
+
+    @property
+    def remove_leading_zeros(self):
+        """`bool`: Strip leading zeros in the formatted number.
+
+        Example usage::
+
+            >>> axis.tick_labels.format.remove_leading_zeros = True
+        """
+        return self._get_style(bool, sv.REMOVELEADINGZEROS)
+
+    @remove_leading_zeros.setter
+    def remove_leading_zeros(self, value):
+        self._set_style(bool(value), sv.REMOVELEADINGZEROS)
+
+    @property
+    def show_decimals_on_whole_numbers(self):
+        """`bool`: Include trailing decimal character with whole numbers.
+
+        Example usage::
+
+            >>> axis.tick_labels.format.show_decimals_on_whole_numbers = True
+        """
+        return self._get_style(bool, sv.SHOWDECIMALSONWHOLENUMBERS)
+
+    @show_decimals_on_whole_numbers.setter
+    def show_decimals_on_whole_numbers(self, value):
+        self._set_style(bool(value), sv.SHOWDECIMALSONWHOLENUMBERS)
+
+    @property
+    def show_negative_sign(self):
+        """`bool`: Include negative sign for negative values.
+
+        Example usage::
+
+            >>> axis.tick_labels.format.show_negative_sign = True
+        """
+        return self._get_style(bool, sv.SHOWNEGATIVESIGN)
+
+    @show_negative_sign.setter
+    def show_negative_sign(self, value):
+        self._set_style(bool(value), sv.SHOWNEGATIVESIGN)
+
+    @property
+    def negative_prefix(self):
+        """`str`: Prefix string to use for negative valued tick labels.
+
+        This example shows how to use parentheses instead of a negative sign::
+
+            >>> axis.tick_labels.format.show_negative_sign = False
+            >>> axis.tick_labels.format.negative_prefix = '('
+            >>> axis.tick_labels.format.negative_suffix = ')'
+        """
+        return self._get_style(str, sv.NEGATIVEPREFIX)
+
+    @negative_prefix.setter
+    def negative_prefix(self, value):
+        self._set_style(str(value), sv.NEGATIVEPREFIX)
+
+    @property
+    def negative_suffix(self):
+        """`str`: Suffix string to use for negative valued tick labels.
+
+        This example shows how to use parentheses instead of a negative sign::
+
+            >>> axis.tick_labels.format.show_negative_sign = False
+            >>> axis.tick_labels.format.negative_prefix = '('
+            >>> axis.tick_labels.format.negative_suffix = ')'
+        """
+        return self._get_style(str, sv.NEGATIVESUFFIX)
+
+    @negative_suffix.setter
+    def negative_suffix(self, value):
+        self._set_style(str(value), sv.NEGATIVESUFFIX)
+
+    @property
+    def positive_prefix(self):
+        """`str`: Prefix string to use for positive valued tick labels.
+
+        Example usage::
+
+            >>> axis.tick_labels.format.positive_prefix = 'increase: '
+        """
+        return self._get_style(str, sv.POSITIVEPREFIX)
+
+    @positive_prefix.setter
+    def positive_prefix(self, value):
+        self._set_style(str(value), sv.POSITIVEPREFIX)
+
+    @property
+    def positive_suffix(self):
+        """`str`: Suffix string to use for positive valued tick labels.
+
+        Example usage::
+
+            >>> axis.tick_labels.format.positive_suffix = ' (m)'
+        """
+        return self._get_style(str, sv.POSITIVESUFFIX)
+
+    @positive_suffix.setter
+    def positive_suffix(self, value):
+        self._set_style(str(value), sv.POSITIVESUFFIX)
+
+    @property
+    def zero_prefix(self):
+        """`str`: Prefix string to use for zero valued tick labels.
+
+        Example usage::
+
+            >>> axis.tick_labels.format.zero_prefix = 'origin: '
+        """
+        return self._get_style(str, sv.ZEROPREFIX)
+
+    @zero_prefix.setter
+    def zero_prefix(self, value):
+        self._set_style(str(value), sv.ZEROPREFIX)
+
+    @property
+    def zero_suffix(self):
+        """`str`: Suffix string to use for zero valued tick labels.
+
+        Example usage::
+
+            >>> axis.tick_labels.format.zero_suffix = ' (origin)'
+        """
+        return self._get_style(str, sv.ZEROSUFFIX)
+
+    @zero_suffix.setter
+    def zero_suffix(self, value):
+        self._set_style(str(value), sv.ZEROSUFFIX)
+
+    @property
+    def datetime_format(self):
+        r"""`str`: The date/time format to be used.
+
+        Example usage::
+
+            >>> from tecplot.constant import NumberFormat
+            >>> axis.tick_labels.format.format_type = NumberFormat.TimeDate
+            >>> axis.tick_labels.format.datetime_format = 'mmm d, yyyy'
+
+        The format can be any combination of the following codes. Placing a
+        backslash in front of a y, m, d, or s in the Time/Date formula will
+        keep it from being processed as part of the formula. All characters not
+        part of the Time/Date formula will appear as entered. For example,
+        "\\year yyyy" will appear as "year 2008", as the backslash keeps the
+        first y from being processed as part of the formula. If you use "m"
+        immediately after the "h" or "hh" code or immediately before the "ss"
+        code, the minutes instead of the month will be displayed.
+
+        =============== =========================
+        Years:
+        -----------------------------------------
+            ``yy``      00-99
+            ``yyyy``    1800-9999
+        --------------- -------------------------
+        Months:
+        -----------------------------------------
+            ``m``       1-12
+            ``mm``      01-12
+            ``mmm``     Jan-Dec
+            ``mmmm``    January-December
+            ``mmmmm``   first letter of the month
+        --------------- -------------------------
+        Days:
+        -----------------------------------------
+            ``[d]``     elapsed days
+            ``d``       1-31
+            ``dd``      01-31
+            ``ddd``     Sun-Sat
+            ``dddd``    Sunday-Saturday
+            ``ddddd``   S,M,T,W,T,F,S
+        --------------- -------------------------
+        Hours:
+        -----------------------------------------
+            ``[h]``     elapsed hours
+            ``h``       0-23 or 1-12
+            ``hh``      00-23 or 1-12
+            ``AM/PM``   AM or PM
+            ``A/P``     AM or PM as "A" or "P"
+        --------------- -------------------------
+        Minutes:
+        -----------------------------------------
+            ``[m]``     elapsed minutes
+            ``m``       0-59
+            ``mm``      00-59
+        --------------- -------------------------
+        Seconds:
+        --------------- -------------------------
+            ``s``       0-59
+            ``ss``      00-59
+            ``.0``      Tenths
+            ``.00``     Hundredths
+            ``.000``    Thousandths
+        =============== =========================
+
+        To display the time and date on your plot as a "Sat-Jan-05-2008", enter
+        the following code::
+
+            "ddd-mmm-dd-yyyy"
+
+        To display the time and date on your plot as a "1-3-08", enter the
+        following code::
+
+            "m-d-yy"
+
+        To display the time and date on your plot as a "9:30:05 AM", enter the
+        following code::
+
+            "h:mm:ss AM"
+
+        To display an elapsed time, such as "3:10:15", enter the following
+        code::
+
+            "[d]:hh:mm"
+        """
+        return self._get_style(str, sv.TIMEDATEFORMAT)
+
+    @datetime_format.setter
+    def datetime_format(self, value):
+        self._set_style(str(value), sv.TIMEDATEFORMAT)

tecplot/text/textbox.py

@@ -0,0 +1,106 @@
+from builtins import super
+
+from ..tecutil import sv
+from .. import constant, session
+
+#
+# Note: The TextBox class is similar to the annotation.TextBox class, except
+# that annotation.TextBox is specific to text annotations and uses the
+# TecUtilText API to get/set properties.
+#
+# The TextBox class below uses style to get/set properties.
+#
+# Therefore, this class must be separate from annotation.TextBox
+#
+
+
+class TextBox(session.Style):
+    """Rectangular frame around a text element.
+
+    .. warning::
+
+        `text.TextBox` objects cannot be created directly. They are returned by
+        various other read-only properties.
+
+    """
+    def __init__(self, parent):
+        self.parent = parent
+        super().__init__(parent._sv, sv.BOX, **parent._kw)
+
+    @property
+    def box_type(self):
+        """`constant.TextBox`: Type of box surrounding the text.
+
+        Example usage::
+
+            >>> plot = frame.plot()
+            >>> plot.legend.box.box_type = constant.TextBox.None_
+        """
+        return self._get_style(constant.TextBox, sv.BOXTYPE)
+
+    @box_type.setter
+    def box_type(self, value):
+        self._set_style(constant.TextBox(value), sv.BOXTYPE)
+
+    @property
+    def color(self):
+        """`Color`: Color of the box surrounding the text.
+
+        Example usage::
+
+            >>> plot = frame.plot()
+            >>> plot.legend.box.color = Color.Blue
+        """
+        return self._get_style(constant.Color, sv.COLOR)
+
+    @color.setter
+    def color(self, value):
+        self._set_style(constant.Color(value), sv.COLOR)
+
+    @property
+    def fill_color(self):
+        """`Color`: Fill color of the box surrounding the text.
+
+        Example usage::
+
+            >>> plot = frame.plot()
+            >>> plot.legend.box.fill_color = Color.Blue
+        """
+        return self._get_style(constant.Color, sv.FILLCOLOR)
+
+    @fill_color.setter
+    def fill_color(self, value):
+        self._set_style(constant.Color(value), sv.FILLCOLOR)
+
+    @property
+    def line_thickness(self):
+        """`float`: Line thickness of the box surrounding the text.
+
+        Example usage::
+
+            >>> plot = frame.plot()
+            >>> plot.legend.box.line_thickness = 0.2
+        """
+        return self._get_style(float, sv.LINETHICKNESS)
+
+    @line_thickness.setter
+    def line_thickness(self, value):
+        self._set_style(float(value), sv.LINETHICKNESS)
+
+    @property
+    def margin(self):
+        """`float`: Margin of the box surrounding the text.
+
+        This property is the margin between the text inside the text box
+        and the box as a percentage of frame height.
+
+        Example usage::
+
+            >>> plot = frame.plot()
+            >>> plot.legend.box.margin = 0.3
+        """
+        return self._get_style(float, sv.MARGIN)
+
+    @margin.setter
+    def margin(self, value):
+        self._set_style(float(value), sv.MARGIN)

tecplot/version.py

@@ -0,0 +1,41 @@
+"""Version information of the tecplot Python module can be obtained as a `string
+<str>` of the form "Major.Minor.Patch"::
+
+    tecplot.__version__
+
+or as a `namedtuple <collections.namedtuple>` with attributes: "major",
+"minor", "patch", "build" in that order::
+
+    tecplot.version_info
+
+The underlying |Tecplot 360| installation has its own version which can be
+obtained as a `str`::
+
+    tecplot.sdk_version
+
+or as a `namedtuple <collections.namedtuple>`::
+
+    tecplot.sdk_version_info
+
+PyTecplot adheres to the semantic versioning as outlined in `SemVer 2.0.0
+<https://semver.org/spec/v2.0.0.html>`__ with regard to backwards compatibility
+between releases. For this purpose, the public interface of PyTecplot is
+defined as all entities (functions, properties etc.) presented in the `HTML
+documentation <https://www.tecplot.com/docs/pytecplot/>`__ and does not include
+methods in the code-base which do not show up in the HTML documentation, even
+when a docstring is present. In short, we will maintain backwards compatibility
+of the public interface between all minor releases of the same major version
+with the exception of internal changes that fix incorrect behavior or bugs.
+"""
+import collections
+
+from .tecutil import _tecutil_connector
+
+Version = collections.namedtuple('V', ['major', 'minor', 'patch', 'build'])
+
+version = '1.5.2'
+build = 'ea41609'
+version_info = Version(*[int(x) for x in version.split('.')], build=build or 0)
+
+sdk_version_info = _tecutil_connector.sdk_version_info
+sdk_version = _tecutil_connector.sdk_version