U /ef@sZdZddlmZddlZeeZddlmZddl m Z ddl m Z ddl mZdd lmZmZdd lmZd d l mZd dlmZd dlmZmZd dlmZmZd dlmZmZd dl m!Z!d dl"m#Z#d dl$m%Z%d dl&m'Z'd dl(m)Z)m*Z*m+Z+m,Z,d dl-m.Z.d dl/m0Z0m1Z1m2Z2m3Z3erLddl4m5Z5ddl6m7Z7ddl8m9Z9dZ:e#dddd Z;e#dddd d!ZGd&d'd'e=Z?Gd(d)d)e?Z@Gd*d+d+e=ZAGd,d-d-e=ZBGd.d/d/e=ZCGd0d1d1e=ZDGd2d3d3e=ZEGd4d5d5e=ZFGd6d7d7e=ZGGd8d9d9e=ZHGd:d;d;e=ZIGdd?d?e=ZKGd@dAdAe?ZLGdBdCdCeLZMGdDdEdEeMZNGdFdGdGeMZOGdHdIdIeOZPGdJdKdKe?ZQGdLdMdMe=ZRGdNdOdOe dPdQZSGdRdSdSe dPdQZTGdTdUdUe dPdQZUdddVdWdOdXdYdZVdedZdWdSd[d\dZWdfd]dWdUd^d_dZXd`daZYdbdcZZdS)gz/ Provide the DataSpec properties and helpers. ) annotationsN) TYPE_CHECKING) TypedDict)colors) deprecated)convert_datetime_typeconvert_timedelta_type) nice_join)enums)Color)DictList)Datetime TimeDelta)DataSpecPropertyDescriptorUnitsSpecPropertyDescriptor)Either)Enum)Instance)Nullable)FloatIntNullString) Undefined) DashPatternFontSizeHatchPatternType MarkerType)Unknown) Expression) Transform) AlphaSpec AngleSpec ColorSpecDashPatternSpecDataSpec DistanceSpecexprfield FontSizeSpec FontStyleSpecHatchPatternSpecIntSpec LineCapSpec LineJoinSpec MarkerSpec NumberSpecSizeSpec StringSpec TextAlignSpecTextBaselineSpecvaluer+r,r9 transformunitscs8eZdZdZd ddfdd ZddZd d ZZS) r)a Base class for properties that accept either a fixed value, or a string name that references a column in a :class:`~bokeh.models.sources.ColumnDataSource`. Many Bokeh models have properties that a user might want to set either to a single fixed value, or to have the property take values from some column in a data source. As a concrete example consider a glyph with an ``x`` property for location. We might want to set all the glyphs that get drawn to have the same location, say ``x=10``. It would be convenient to just be able to write: .. code-block:: python glyph.x = 10 Alternatively, maybe the each glyph that gets drawn should have a different location, according to the "pressure" column of a data source. In this case we would like to be able to write: .. code-block:: python glyph.x = "pressure" Bokeh ``DataSpec`` properties (and subclasses) afford this ease of and consistency of expression. Ultimately, all ``DataSpec`` properties resolve to dictionary values, with either a ``"value"`` key, or a ``"field"`` key, depending on how it is set. For instance: .. code-block:: python glyph.x = 10 # => { 'value': 10 } glyph.x = "pressure" # => { 'field': 'pressure' } When these underlying dictionary dictionary values are received in the browser, BokehJS knows how to interpret them and take the correct, expected action (i.e., draw the glyph at ``x=10``, or draw the glyph with ``x`` coordinates from the "pressure" column). In this way, both use-cases may be expressed easily in python, without having to handle anything differently, from the user perspective. It is worth noting that ``DataSpec`` properties can also be set directly with properly formed dictionary values: .. code-block:: python glyph.x = { 'value': 10 } # same as glyph.x = 10 glyph.x = { 'field': 'pressure' } # same as glyph.x = "pressure" Setting the property directly as a dict can be useful in certain situations. For instance some ``DataSpec`` subclasses also add a ``"units"`` key to the dictionary. This key is often set automatically, but the dictionary format provides a direct mechanism to override as necessary. Additionally, ``DataSpec`` can have a ``"transform"`` key, that specifies a client-side transform that should be applied to any fixed or field values before they are uses. As an example, you might want to apply a ``Jitter`` transform to the ``x`` values: .. code-block:: python glyph.x = { 'value': 10, 'transform': Jitter(width=0.4) } Note that ``DataSpec`` is not normally useful on its own. Typically, a model will define properties using one of the subclasses such as :class:`~bokeh.core.properties.NumberSpec` or :class:`~bokeh.core.properties.ColorSpec`. For example, a Bokeh model with ``x``, ``y`` and ``color`` properties that can handle fixed values or columns automatically might look like: .. code-block:: python class SomeModel(Model): x = NumberSpec(default=0, help="docs for x") y = NumberSpec(default=0, help="docs for y") color = ColorSpec(help="docs for color") # defaults to None NNonereturnc sRtjtt|tttdtd||||d|||_|tddddS)Nz!bokeh.models.transforms.Transformz#bokeh.models.expressions.ExpressiondefaulthelpcSst|SNr+)objrE@/tmp/pip-unpacked-wheel-f5fndrjf/bokeh/core/property/dataspec.pyz#DataSpec.__init__..) super__init__rrrr_validate_type_param_typeaccepts)selfkey_typeZ value_typer@rA __class__rErFrJs" zDataSpec.__init__cCs t||gS)a Return a list of ``DataSpecPropertyDescriptor`` instances to install on a class, in order to delegate attribute access to this property. Args: base_name (str) : the name of the property these descriptors are for Returns: list[DataSpecPropertyDescriptor] The descriptors returned are collected by the ``MetaHasProps`` metaclass and added to ``HasProps`` subclasses during class creation. )r)rN base_namerErErFmake_descriptorsszDataSpec.make_descriptorscCsLz|j|dt|dWStk r.YnXt|trDt|dSt|S)NFr9r,)rLvalidatedict ValueError isinstancestrrNrDnamevalrErErFto_serializables   zDataSpec.to_serializable)N)__name__ __module__ __qualname____doc__rJrSr^ __classcell__rErErPrFr)fsSr)cs(eZdZdefddfdd ZZS)r0Nr<r=cstj|t||ddSNr?)rIrJrrNr@rArOrPrErFrJszIntSpec.__init__r_r`ra_ExprFieldValueTransformrJrcrErErPrFr0sr0cs2eZdZdZededdfddfdd ZZS)r4au A |DataSpec| property that accepts numeric and datetime fixed values. By default, date and datetime values are immediately converted to milliseconds since epoch. It is possible to disable processing of datetime values by passing ``accept_datetime=False``. By default, timedelta values are immediately converted to absolute milliseconds. It is possible to disable processing of timedelta values by passing ``accept_timedelta=False`` Timedelta values are interpreted as absolute milliseconds. .. code-block:: python m.location = 10.3 # value m.location = "foo" # field NTr<r=cs8tj|t||d|r$|tt|r4|ttdSrd)rIrJrrMrr rr)rNr@rArOaccept_datetimeaccept_timedeltarPrErFrJs  zNumberSpec.__init__)r_r`rarbrrgrJrcrErErPrFr4sr4cs(eZdZdZdddfdd ZZS) r%zK Acceptable values are numbers in 0..1 range (transparent..opaque). ?Nr<r=cs.|pdd|j}tj||tddddS)N F)r@rArOrhri) _default_helprIrJrg)rNr@rArPrErFrJszAlphaSpec.__init__)rjN)r_r`rarmrJrcrErErPrFr% sr%cs*eZdZddefddfdd ZZS)NullStringSpecNr<r=cs tj|ttt||ddSrd)rIrJrrrrerPrErFrJszNullStringSpec.__init__rfrErErPrFrnsrncs8eZdZdZdefddfdd ZfddZZS) r6a A |DataSpec| property that accepts string fixed values. Because acceptable fixed values and field names are both strings, it can be necessary explicitly to disambiguate these possibilities. By default, string values are interpreted as fields, but the |value| function can be used to specify that a string should interpreted as a value: .. code-block:: python m.title = value("foo") # value m.title = "foo" # field Nr<r=cstj|tt||ddSrd)rIrJrrrerPrErFrJ(szStringSpec.__init__cs<t|tr,t|dkrtdt|dd}t|||S)Nr z5StringSpec convenience list values must have length 1rrT)rYlistlen TypeErrorrWrI prepare_valuerNclsr\r9rPrErFrr+s   zStringSpec.prepare_value)r_r`rarbrgrJrrrcrErErPrFr6sr6cs:eZdZdZdefddfdd Zd fdd ZZS) r-a A |DataSpec| property that accepts font-size fixed values. The ``FontSizeSpec`` property attempts to first interpret string values as font sizes (i.e. valid CSS length values). Otherwise string values are interpreted as field names. For example: .. code-block:: python m.font_size = "13px" # value m.font_size = "1.5em" # value m.font_size = "foo" # field A full list of all valid CSS length units can be found here: https://drafts.csswg.org/css-values/#lengths Nr<r=cstj|t||ddSrd)rIrJrrerPrErFrJGszFontSizeSpec.__init__TcsZt||t|trVt|dks<|drVtj|sV|sDdn|d}t |dS)Nrrkz is not a valid font size value) rIrVrYrZrpisdigitrZ _font_size_rematchrX)rNr9ZdetailmsgrPrErFrVJs  $zFontSizeSpec.validate)T)r_r`rarbrgrJrVrcrErErPrFr-2sr-cs(eZdZdefddfdd ZZS)r.Nr<r=cstj|ttj||ddSrd)rIrJrr Z FontStylererPrErFrJUszFontStyleSpec.__init__rfrErErPrFr.Tsr.cs(eZdZdefddfdd ZZS)r7Nr<r=cstj|ttj||ddSrd)rIrJrr Z TextAlignrerPrErFrJYszTextAlignSpec.__init__rfrErErPrFr7Xsr7cs(eZdZdefddfdd ZZS)r8Nr<r=cstj|ttj||ddSrd)rIrJrr Z TextBaselinererPrErFrJ]szTextBaselineSpec.__init__rfrErErPrFr8\sr8cs(eZdZdefddfdd ZZS)r2Nr<r=cstj|ttj||ddSrd)rIrJrr ZLineJoinrerPrErFrJaszLineJoinSpec.__init__rfrErErPrFr2`sr2cs(eZdZdefddfdd ZZS)r1Nr<r=cstj|ttj||ddSrd)rIrJrr ZLineCaprerPrErFrJeszLineCapSpec.__init__rfrErErPrFr1dsr1cs(eZdZdefddfdd ZZS)r(Nr<r=cstj|t||ddSrd)rIrJrrerPrErFrJiszDashPatternSpec.__init__rfrErErPrFr(hsr(cs,eZdZdZdefddfdd ZZS)r/a A |DataSpec| property that accepts hatch pattern types as fixed values. The ``HatchPatternSpec`` property attempts to first interpret string values as hatch pattern types. Otherwise string values are interpreted as field names. For example: .. code-block:: python m.font_size = "." # value m.font_size = "ring" # value m.font_size = "foo" # field Nr<r=cstj|tt||ddSrd)rIrJrr rerPrErFrJ}szHatchPatternSpec.__init__r_r`rarbrgrJrcrErErPrFr/lsr/cs,eZdZdZdefddfdd ZZS)r3a A |DataSpec| property that accepts marker types as fixed values. The ``MarkerSpec`` property attempts to first interpret string values as marker types. Otherwise string values are interpreted as field names. For example: .. code-block:: python m.font_size = "circle" # value m.font_size = "square" # value m.font_size = "foo" # field Nr<r=cstj|t||ddSrd)rIrJr!rerPrErFrJszMarkerSpec.__init__rxrErErPrFr3sr3csReZdZdZdddfdd Zdddd Zd d Zd d ZfddZZ S) UnitsSpecz A |DataSpec| property that accepts numeric fixed values, and also provides an associated units property to store units information. Nr<r=csBtj||tdt||ddt|dd}|j|dd|_dS)N)r@rArOFz3 Units to use for the associated property: z )r@Z serializedrAT)Z help_allowed)rIrJ_ExprFieldValueTransformUnitsrr rK _units_type)rNr@ units_enum units_defaultrAZ units_typerPrErFrJs   zUnitsSpec.__init__rZcCs|jj}|jjd|dS)Nz(units_default=))r{_defaultrQr_)rNr}rErErF__str__szUnitsSpec.__str__cCst||dS)N_units)getattr)rNrDr\rErErF get_unitsszUnitsSpec.get_unitscCs*|d}|j|}|t|||dgS)a Return a list of ``PropertyDescriptor`` instances to install on a class, in order to delegate attribute access to this property. Unlike simpler property types, ``PropertyUnitsSpec`` returns multiple descriptors to install. In particular, descriptors for the base property as well as the associated units property are returned. Args: name (str) : the name of the property these descriptors are for Returns: list[PropertyDescriptor] The descriptors returned are collected by the ``MetaHasProps`` metaclass and added to ``HasProps`` subclasses during class creation. rr)r{rSr)rNrRZ units_nameZ units_propsrErErFrSs zUnitsSpec.make_descriptorscsNt|||}|dk rJd|krJ|||}||jjkrJtf|d|i}|S)Nr;)rIr^rr{rrW)rNrDr\r]dr;rPrErFr^s   zUnitsSpec.to_serializable)N) r_r`rarbrJrrrSr^rcrErErPrFrys ryc@s eZdZdS)PropertyUnitsSpecN)r_r`rarErErErFrsrcs.eZdZdZeddfddfdd ZZS)r&z A |DataSpec| property that accepts numeric fixed values, and also provides an associated units property to store angle units. Acceptable values for units are ``"deg"``, ``"rad"``, ``"grad"`` and ``"turn"``. ZradNr<r=cstj|tj||ddSN)r@r|r}rA)rIrJr Z AngleUnitsrNr@r}rArPrErFrJszAngleSpec.__init__)r_r`rarbrrJrcrErErPrFr&sr&cs:eZdZdZeddfddfdd Zfdd ZZS) r*a) A |DataSpec| property that accepts numeric fixed values or strings that refer to columns in a :class:`~bokeh.models.sources.ColumnDataSource`, and also provides an associated units property to store units information. Acceptable values for units are ``"screen"`` and ``"data"``. dataNr<r=cstj|tj||ddSr)rIrJr Z SpatialUnitsrrPrErFrJszDistanceSpec.__init__cs:z|dkrtdWntk r(YnXt|||S)NrzDistances must be positive!rXrqrIrrrsrPrErFrrs  zDistanceSpec.prepare_value)r_r`rarbrrJrrrcrErErPrFr*sr*cs0eZdZd ddfdd ZfddZZS) NullDistanceSpecNrr<r=cs2tj|||dt|j|_tg|j|_dS)N)r@r}rA)rIrJrrLrZ _type_paramsrrPrErFrJs zNullDistanceSpec.__init__csBz|dk r|dkrtdWntk r0YnXt|||S)Nrz#Distances must be positive or None!rrsrPrErFrrs  zNullDistanceSpec.prepare_value)NrN)r_r`rarJrrrcrErErPrFrsrcs eZdZdZfddZZS)r5z A |DataSpec| property that accepts non-negative numeric fixed values for size values or strings that refer to columns in a :class:`~bokeh.models.sources.ColumnDataSource`. cs:z|dkrtdWntk r(YnXt|||S)NrzScreen sizes must be positiverrsrPrErFrrs  zSizeSpec.prepare_value)r_r`rarbrrrcrErErPrFr5sr5cs\eZdZdZdZdefddfdd Zedd Zed d Z d d Z fddZ Z S)r'a A |DataSpec| property that accepts |Color| fixed values. The ``ColorSpec`` property attempts to first interpret string values as colors. Otherwise, string values are interpreted as field names. For example: .. code-block:: python m.color = "#a4225f" # value (hex color string) m.color = "firebrick" # value (named CSS color string) m.color = "foo" # field (named "foo") This automatic interpretation can be override using the dict format directly, or by using the |field| function: .. code-block:: python m.color = { "field": "firebrick" } # field (named "firebrick") m.color = field("firebrick") # field (named "firebrick") a Acceptable values are: - any of the |named CSS colors|, e.g ``'green'``, ``'indigo'`` - RGB(A) hex strings, e.g., ``'#FF0000'``, ``'#44444444'`` - CSS4 color strings, e.g., ``'rgba(255, 0, 127, 0.6)'``, ``'rgb(0 127 0 / 1.0)'`` - a 3-tuple of integers (r, g, b) between 0 and 255 - a 4-tuple of (r, g, b, a) where r, g, b are integers between 0..255 and a is between 0..1 - a 32-bit unsiged integers using the 0xRRGGBBAA byte order pattern Nr<r=cs0|pdd|j}tj|tt||ddS)Nrkrlr?)rmrIrJrrrerPrErFrJ+szColorSpec.__init__cCs,t|to*t|dkr"|ddkp*|tjkS)a Whether the value is a string color literal. Checks for a well-formed hexadecimal color value or a named color. Args: val (str) : the value to check Returns: True, if the value is a string color literal r#)rYrZrpr Z NamedColorrtr]rErErFisconst/s  zColorSpec.isconstcCs(t|to&t|dko&tdd|DS)z Whether the value is the correct shape to be a color tuple Checks for a 3 or 4-tuple of numbers Args: val (str) : the value to check Returns: True, if the value could be a color tuple )rcss|]}t|ttfVqdSrB)rYfloatint).0vrErErF Lsz1ColorSpec.is_color_tuple_shape..)rYtuplerpallrrErErFis_color_tuple_shape?s zColorSpec.is_color_tuple_shapecCs|dkrtddS||r&t|dSt|trDttj|dSt|tjrX|St|trz|drp|St|dSt|S)NrT)zrgb(zrgba(rU) rWrrYrrZRGBZto_cssrZ startswithr[rErErFr^Ns        zColorSpec.to_serializablecs0||r tddt|D}t|||S)Ncss&|]\}}|dkrt|n|VqdS)rN)r)rirrErErFrrsz*ColorSpec.prepare_value..)rr enumeraterIrrrsrPrErFrrhs zColorSpec.prepare_value) r_r`rarbrmrgrJ classmethodrrr^rrrcrErErPrFr's   r'c@seZdZUded<ded<dS)Exprr#r+Transform | Noner:Nr_r`ra__annotations__rErErErFrws rF)totalc@seZdZUded<ded<dS)FieldrZr,rr:NrrErErErFr{s rc@seZdZUded<ded<dS)Valuer"r9rr:NrrErErErFrs rr#r) expressionr:r>cCs|rt||dSt|dS)a Convenience function to explicitly return an "expr" specification for a Bokeh |DataSpec| property. Args: expression (Expression) : a computed expression for a ``DataSpec`` property. transform (Transform, optional) : a transform to apply (default: None) Returns: dict : ``{ "expr": expression }`` .. note:: This function is included for completeness. String values for property specifications are by default interpreted as field names. )r+r:rC)r)rr:rErErFr+s rZ)r\r:r>cCs|rt||dSt|dS)a Convenience function to explicitly return a "field" specification for a Bokeh |DataSpec| property. Args: name (str) : name of a data source field to reference for a ``DataSpec`` property. transform (Transform, optional) : a transform to apply (default: None) Returns: dict : ``{ "field": name }`` .. note:: This function is included for completeness. String values for property specifications are by default interpreted as field names. )r,r:rU)r)r\r:rErErFr,s r")r]r:r>cCs|rt||dSt|dS)a_ Convenience function to explicitly return a "value" specification for a Bokeh |DataSpec| property. Args: val (any) : a fixed value to specify for a ``DataSpec`` property. transform (Transform, optional) : a transform to apply (default: None) Returns: dict : ``{ "value": name }`` .. note:: String values for property specifications are by default interpreted as field names. This function is especially useful when you want to specify a fixed value with text properties. Example: .. code-block:: python # The following will take text values to render from a data source # column "text_column", but use a fixed value "16px" for font size p.text("x", "y", text="text_column", text_font_size=value("16px"), source=source) )r9r:rT)r)r]r:rErErFr9s cOstdddt||SN)r rrzDataDistanceSpec()z SizeSpec()rr5argskwrErErFDataDistanceSpecs rcOstdddt||SrrrrErErFScreenDistanceSpecs r)N)N)N)[rb __future__rlogging getLoggerr_logtypingrZtyping_extensionsrrkrZutil.deprecationrZutil.serializationrr Z util.stringr r colorr containerrrdatetimerrZ descriptorsrrZeitherrenumrinstancerZnullablerZ primitiverrrrZ singletonsrvisualrrr r!Z core.typesr"Zmodels.expressionsr#Zmodels.transformsr$__all__rgrzr)r0r4r%rnr6r-r.r7r8r2r1r(r/r3ryrr&r*rr5r'rrrr+r,r9rrrErErErFsv                  "5 r#