HEX

File: //home/arjun/projects/env/lib/python3.10/site-packages/docx/__pycache__/shared.cpython-310.pyc
o

$we�4�@sddZddlmZddlZddlmZmZmZmZm	Z	m
Z
mZmZm
Z
er<ddlmZddlmZddlmZddlmZGd	d
�d
e�ZGdd�de�ZGd
d�de�ZGdd�de�ZGdd�de�ZGdd�de�ZGdd�de�ZGdd�deeeef�Zed�Z Gdd�dee �Z!d(dd�Z"Gd d!�d!�Z#Gd"d#�d#�Z$Gd$d%�d%�Z%Gd&d'�d'�Z&dS))zObjects shared by docx modules.�)�annotationsN)	�
TYPE_CHECKING�Any�Callable�Generic�Iterator�List�Tuple�TypeVar�cast)�types)�XmlPart)�BaseOxmlElement)�	StoryPartc@sveZdZdZdZdZdZdZdZdd	d
�Z	e
dd��Ze
d
d��Ze
dd��Z
e
dd��Ze
dd��Ze
dd��ZdS)�Lengtha
Base class for length constructor classes Inches, Cm, Mm, Px, and Emu.

    Behaves as an int count of English Metric Units, 914,400 to the inch, 36,000 to the
    mm. Provides convenience unit conversion methods in the form of read-only
    properties. Immutable.
    i��
i@~i��i�1i{�emu�intcCst�||�S�N)r�__new__��clsr�r�D/home/arjun/projects/env/lib/python3.10/site-packages/docx/shared.pyr'szLength.__new__cC�|t|j�S)z7The equivalent length expressed in centimeters (float).)�float�_EMUS_PER_CM��selfrrr�cm*�z	Length.cmcCs|S)z>The equivalent length expressed in English Metric Units (int).rrrrrr/sz
Length.emucCr)z2The equivalent length expressed in inches (float).)r�_EMUS_PER_INCHrrrr�inches4rz
Length.inchescCr)z7The equivalent length expressed in millimeters (float).)r�_EMUS_PER_MMrrrr�mm9rz	Length.mmcCr)z Floating point length in points.)r�_EMUS_PER_PTrrrr�pt>rz	Length.ptcCstt|t|j���S)z/The equivalent length expressed in twips (int).)r�roundr�_EMUS_PER_TWIPrrrr�twipsCszLength.twipsN�rr)�__name__�
__module__�__qualname__�__doc__r rr"r$r'r�propertyrrr!r#r%r(rrrrrs(





rc@�eZdZdZddd�ZdS)�IncheszKConvenience constructor for length in inches, e.g. ``width = Inches(0.5)``.r!rcC�t|tj�}t�||�Sr)rrr r)rr!rrrrrL�zInches.__new__N)r!r�r*r+r,r-rrrrrr0I�r0c@r/)�CmzLConvenience constructor for length in centimeters, e.g. ``height = Cm(12)``.rrcCr1r)rrrr)rrrrrrrTr2z
Cm.__new__N)rrr3rrrrr5Qr4r5c@r/)�Emuz]Convenience constructor for length in English Metric Units, e.g. ``width =
    Emu(457200)``.rrcCst�|t|��Sr)rrrrrrrr]szEmu.__new__Nr)r3rrrrr6Ysr6c@r/)�MmzNConvenience constructor for length in millimeters, e.g. ``width = Mm(240.5)``.r#rcCr1r)rrr"r)rr#rrrrrdr2z
Mm.__new__N)r#rr3rrrrr7ar4r7c@r/)�Ptz:Convenience value class for specifying a length in points.�pointsrcCr1r)rrr$r)rr9rrrrrlr2z
Pt.__new__N)r9rr3rrrrr8ir4r8c@r/)�Twipsz}Convenience constructor for length in twips, e.g. ``width = Twips(42)``.

    A twip is a twentieth of a point, 635 EMU.
    r(rcCr1r)rrr'r)rr(rrrrrwr2z
Twips.__new__N)r(rr3rrrrr:qsr:cs@eZdZdZd�fdd�Zdd	�Zd
d�Zeddd��Z�Z	S)�RGBColorz7Immutable value object defining a particular RGB color.�rr�g�bcsNd}|||fD]}t|t�r|dks|dkrt|��qtt|��||||f�S)Nz+RGBColor() takes three integer values 0-255r�)�
isinstancer�
ValueError�superr;r)rr<r=r>�msg�val��	__class__rrrs��zRGBColor.__new__cC�d|S)Nz RGBColor(0x%02x, 0x%02x, 0x%02x)rrrrr�__repr__�szRGBColor.__repr__cCrG)z-Return a hex string rgb value, like '3C2F80'.z%02X%02X%02Xrrrrr�__str__�szRGBColor.__str__�rgb_hex_str�str�returncCsBt|dd�d�}t|dd�d�}t|dd�d�}||||�S)zEReturn a new instance from an RGB color hex string like ``'3C2F80'``.N���)r)rrJr<r=r>rrr�from_string�szRGBColor.from_string)r<rr=rr>r)rJrKrLr;)
r*r+r,r-rrHrI�classmethodrP�
__classcell__rrrErr;|sr;�Tc@s0eZdZdZddd�Zddd
d�Zddd�ZdS)�lazypropertya+Decorator like @property, but evaluated only on first access.

    Like @property, this can only be used to decorate methods having only a `self`
    parameter, and is accessed like an attribute on an instance, i.e. trailing
    parentheses are not used. Unlike @property, the decorated method is only evaluated
    on first access; the resulting value is cached and that same value returned on
    second and later access without re-evaluation of the method.

    Like @property, this class produces a *data descriptor* object, which is stored in
    the __dict__ of the *class* under the name of the decorated method ('fget'
    nominally). The cached value is stored in the __dict__ of the *instance* under that
    same name.

    Because it is a data descriptor (as opposed to a *non-data descriptor*), its
    `__get__()` method is executed on each access of the decorated attribute; the
    __dict__ item of the same name is "shadowed" by the descriptor.

    While this may represent a performance improvement over a property, its greater
    benefit may be its other characteristics. One common use is to construct
    collaborator objects, removing that "real work" from the constructor, while still
    only executing once. It also de-couples client code from any sequencing
    considerations; if it's accessed from more than one location, it's assured it will
    be ready whenever needed.

    Loosely based on: https://stackoverflow.com/a/6849299/1902513.

    A lazyproperty is read-only. There is no counterpart to the optional "setter" (or
    deleter) behavior of an @property. This is critically important to maintaining its
    immutability and idempotence guarantees. Attempting to assign to a lazyproperty
    raises AttributeError unconditionally.

    The parameter names in the methods below correspond to this usage example::

        class Obj(object)

            @lazyproperty
            def fget(self):
                return 'some result'

        obj = Obj()

    Not suitable for wrapping a function (as opposed to a method) because it is not
    callable.�fget�Callable[..., T]rL�NonecCs||_|j|_t�||�dS)aY*fget* is the decorated method (a "getter" function).

        A lazyproperty is read-only, so there is only an *fget* function (a regular
        @property can also have an fset and fdel function). This name was chosen for
        consistency with Python's `property` class which uses this name for the
        corresponding parameter.
        N)�_fgetr*�_name�	functools�update_wrapper)rrUrrr�__init__�s	zlazyproperty.__init__N�objr�typerScCsB|dur|S|j�|j�}|dur|�|�}||j|j<tt|�S)aCalled on each access of 'fget' attribute on class or instance.

        *self* is this instance of a lazyproperty descriptor "wrapping" the property
        method it decorates (`fget`, nominally).

        *obj* is the "host" object instance when the attribute is accessed from an
        object instance, e.g. `obj = Obj(); obj.fget`. *obj* is None when accessed on
        the class, e.g. `Obj.fget`.

        *type* is the class hosting the decorated getter method (`fget`) on both class
        and instance attribute access.
        N)�__dict__�getrYrXrrS)rr]r^�valuerrr�__get__�s

zlazyproperty.__get__racCstd��)a�Raises unconditionally, to preserve read-only behavior.

        This decorator is intended to implement immutable (and idempotent) object
        attributes. For that reason, assignment to this property must be explicitly
        prevented.

        If this __set__ method was not present, this descriptor would become a
        *non-data descriptor*. That would be nice because the cached value would be
        accessed directly once set (__dict__ attrs have precedence over non-data
        descriptors on instance attribute lookup). The problem is, there would be
        nothing to stop assignment to the cached value, which would overwrite the result
        of `fget()` and break both the immutability and idempotence guarantees of this
        decorator.

        The performance with this __set__() method in place was roughly 0.4 usec per
        access when measured on a 2.8GHz development machine; so quite snappy and
        probably not a rich target for optimization efforts.
        zcan't set attribute)�AttributeError)rr]rarrr�__set__�szlazyproperty.__set__)rUrVrLrWr)r]rr^rrLrS)r]rrarrLrW)r*r+r,r-r\rbrdrrrrrT�s

,rT�f�Callable[[Any, Any], None]cCs|j}t||d�S)z�@write_only_property decorator.

    Creates a property (descriptor attribute) that accepts assignment, but not getattr
    (use in an expression).
    )�fset�doc)r-r.)re�	docstringrrr�write_only_propertysrjc@sLeZdZdZ	dddd�Zddd�Zdd
d�Zedd��Zeddd��Z	dS)�ElementProxya,Base class for lxml element proxy classes.

    An element proxy class is one whose primary responsibilities are fulfilled by
    manipulating the attributes and child elements of an XML element. They are the most
    common type of class in python-docx other than custom element (oxml) classes.
    N�elementr�parent�t.ProvidesXmlPart | NonecCs||_||_dSr)�_element�_parent)rrlrmrrrr\s
zElementProxy.__init__�other�objectcCst|t�sdS|j|juS)aTReturn |True| if this proxy object refers to the same oxml element as does
        `other`.

        ElementProxy objects are value objects and should maintain no mutable local
        state. Equality for proxy objects is defined as referring to the same XML
        element, whether or not they are the same proxy object instance.
        F�r@rkro�rrqrrr�__eq__%s
zElementProxy.__eq__cCst|t�sdS|j|juS)NTrsrtrrr�__ne__1s
zElementProxy.__ne__cCs|jS)z(The lxml element proxied by this object.)rorrrrrl6szElementProxy.elementrLr
cCs|jdur	td��|jjS)�(The package part containing this object.Nz(part is not accessible from this element)rprA�partrrrrrx;s
zElementProxy.partr)rlrrmrn)rqrr)rLr
)
r*r+r,r-r\rurvr.rlrxrrrrrks�


rkc@s&eZdZdZd	dd�Zedd��ZdS)
�Parentedz�Provides common services for document elements that occur below a part but may
    occasionally require an ancestor object to provide a service, such as add or drop a
    relationship.

    Provides ``self._parent`` attribute to subclasses.
    rm�t.ProvidesXmlPartcC�
||_dSr�rp�rrmrrrr\K�
zParented.__init__cC�|jjS�rw�rprxrrrrrxN�z
Parented.partN)rmrz�r*r+r,r-r\r.rxrrrrryCs

ryc@s(eZdZdZddd�Zeddd	��Zd
S)
�
StoryChilda�A document element within a story part.

    Story parts include DocumentPart and Header/FooterPart and can contain block items
    (paragraphs and tables). Items from the block-item subtree occasionally require an
    ancestor object to provide access to part-level or package-level items like styles
    or images or to add or drop a relationship.

    Provides `self._parent` attribute to subclasses.
    rm�t.ProvidesStoryPartcCr{rr|r}rrrr\_r~zStoryChild.__init__rLrcCrr�r�rrrrrxbr�zStoryChild.partN)rmr�)rLrr�rrrrr�Ts


r�c@s0eZdZdZdddd�Zdd
d�Zdd
d�ZdS)�TextAccumulatora>Accepts `str` fragments and joins them together, in order, on `.pop().

    Handy when text in a stream is broken up arbitrarily and you want to join it back
    together within certain bounds. The optional `separator` argument determines how
    the text fragments are punctuated, defaulting to the empty string.
    ��	separatorrKcCs||_g|_dSr)�
_separator�_texts)rr�rrrr\ps
zTextAccumulator.__init__�textrLrWcCs|j�|�dS)z'Add a text fragment to the accumulator.N)r��append�rr�rrr�pushtszTextAccumulator.push�
Iterator[str]ccs.�|jsdS|j�|j�}|j��|VdS)z�Generate sero-or-one str from those accumulated.

        Using `yield from accum.pop()` in a generator setting avoids producing an empty
        string when no text is in the accumulator.
        N)r�r��join�clearr�rrr�popxs�

zTextAccumulator.popN)r�)r�rK)r�rKrLrW)rLr�)r*r+r,r-r\r�r�rrrrr�hs

r�)rerf)'r-�
__future__rrZ�typingrrrrrrr	r
r�docxr�t�
docx.opc.partr
�docx.oxml.xmlchemyr�docx.parts.storyrrrr0r5r6r7r8r:r;rSrTrjrkryr�r�rrrr�<module>s0,0
o,