PyShadowString (Jython API documentation)
Date: 2024-08-18

org.python.core

## Class PyShadowString

- java.lang.Object
- - org.python.core.PyObject
  - - org.python.core.PySequence
    - - org.python.core.PyBaseString
      - - org.python.core.PyString
        - - org.python.core.PyShadowString

- All Implemented Interfaces:
    java.io.Serializable, java.lang.CharSequence, BufferProtocol
  Direct Known Subclasses:
    PyShadowStringDerived

      public class PyShadowString
      extends PyString

  This class provides a string that sometimes seems to change value, as far as equality tests and `startswith` are concerned. This solves a problem that Jython users sometimes experience with libraries that are sensitive to platform.

  A library may test for a particular platform in order to adjust to local file name conventions or to decide which operating system commands are available. In Jython, `os.name` and `sys.platform` indicate that Java is the platform, which is necessary information in some parts of the standard library, but other libraries assuming CPython then draw incorrect conclusions.

  With hindsight, a better choice could be made, where `sys.platform` etc. indicated Windows or Posix, and something else indicates the implementation. A change in Jython 2 would cause more problems than it solved, but we expect Jython 3 to work that way. In the Python Standard Library, the Jython project can make all necessary changes. It can't do anything about third-party libraries. But it would be a big help if users could cause `sys.platform` or `os.name` to appear to have the OS-dependent value as far as those troublesome libraries were concerned.

  This is what this class achieves. `os.name` and `sys.platform` regular strings for most purposes, but each has a "shadow" value that is used in contexts the user may specify.

  See Also:
    Serialized Form

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.python.core.PyObject

      `PyObject.ConversionException`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static PyType` | `TYPE`

    - ### Fields inherited from class org.python.core.PyObject

      `gcMonitorGlobal`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PyShadowString()` Empty string (not very useful but needed for technical reasons).
    `PyShadowString(PyObject primary, java.lang.String shadow)` Deprecated. use the constructor with strings instead.
    `PyShadowString(PyType subtype, PyObject primary, PyObject shadow)`
    `PyShadowString(java.lang.String primary, java.lang.String shadow)` Construct an instance specifying primary and shadow values.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `PyObject` | `__eq__(PyObject other)` Compare this `PyShadowString` with another `PyObject` for equality.
    `PyObject` | `__getslice__(PyObject start, PyObject stop, PyObject step)`
    `PyString` | `__repr__()` Equivalent to the standard Python `__repr__` method.
    `void` | `addTarget(java.lang.String className, java.lang.String methodName)` Specify a context (class, method) in which the shadow string is allowed to match.
    `PyString` | `getshadow()` Get the shadow value.
    `PyList` | `getTargets()` Return a list of the tuples specifying the contexts in which the shadow value will be consulted during matching.
    `void` | `shadowstr_addtarget(PyObject classname, PyObject methodname)`
    `PyString` | `shadowstr_getshadow()`
    `PyObject` | `shadowstr_gettargets()`
    `boolean` | `startswith(PyObject prefix)` Equivalent to the Python `str.startswith` method testing whether a string starts with a specified prefix.
    `boolean` | `startswith(PyObject prefix, PyObject start)` Equivalent to the Python `str.startswith` method, testing whether a string starts with a specified prefix, where a sub-range is specified by `[start:]`.
    `boolean` | `startswith(PyObject prefix, PyObject start, PyObject end)` Equivalent to the Python `str.startswith` method, testing whether a string starts with a specified prefix, where a sub-range is specified by `[start:end]`.

    - ### Methods inherited from class org.python.core.PyString

      `__add__, __cmp__, __complex__, __contains__, __float__, __format__, __ge__, __getnewargs__, __gt__, __int__, __invert__, __le__, __len__, __long__, __lt__, __mod__, __mul__, __ne__, __neg__, __pos__, __rmul__, __str__, __tojava__, __unicode__, asDouble, asInt, asLong, asName, asString, asString, atof, atoi, atoi, atol, atol, capitalize, center, charAt, count, count, count, count, count, count, createInstance, decode_UnicodeEscape, decode, decode, decode, encode_UnicodeEscape, encode, encode, encode, endswith, endswith, endswith, expandtabs, expandtabs, find, find, find, find, find, find, fromInterned, getBuffer, getInt, getString, hashCode, index, index, index, index, index, index, internedString, isalnum, isalpha, isBasicPlane, isdecimal, isdigit, islower, isnumeric, isspace, istitle, isunicode, isupper, join, length, ljust, ljust, lower, lstrip, lstrip, lstrip, partition, replace, replace, rfind, rfind, rfind, rfind, rfind, rfind, rindex, rindex, rindex, rindex, rindex, rindex, rjust, rpartition, rsplit, rsplit, rsplit, rsplit, rsplit, rstrip, rstrip, rstrip, split, split, split, split, split, splitlines, splitlines, str___mod__, strip, strip, strip, subSequence, substring, swapcase, title, toBytes, toCodePoints, toString, translate, translate, translate, translate, upper, zfill`

    - ### Methods inherited from class org.python.core.PySequence

      `__delitem__, __delslice__, __finditem__, __finditem__, __getitem__, __iter__, __nonzero__, __setitem__, __setitem__, __setslice__, isMappingType, isNumberType, isSequenceType`

    - ### Methods inherited from class org.python.core.PyObject

      `__abs__, __and__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __coerce__, __coerce_ex__, __delattr__, __delattr__, __delete__, __delitem__, __delslice__, __dir__, __div__, __divmod__, __ensure_finalizer__, __findattr__, __findattr__, __findattr_ex__, __finditem__, __floordiv__, __get__, __getattr__, __getattr__, __getitem__, __getslice__, __hash__, __hex__, __iadd__, __iand__, __idiv__, __idivmod__, __ifloordiv__, __ilshift__, __imod__, __imul__, __index__, __ior__, __ipow__, __irshift__, __isub__, __iternext__, __itruediv__, __ixor__, __lshift__, __not__, __oct__, __or__, __pow__, __pow__, __radd__, __rand__, __rdiv__, __rdivmod__, __reduce__, __reduce_ex__, __reduce_ex__, __rfloordiv__, __rlshift__, __rmod__, __ror__, __rpow__, __rrshift__, __rshift__, __rsub__, __rtruediv__, __rxor__, __set__, __setattr__, __setattr__, __setitem__, __setslice__, __sub__, __truediv__, __trunc__, __xor__, _add, _and, _callextra, _cmp, _div, _divmod, _doget, _doget, _doset, _eq, _floordiv, _ge, _gt, _iadd, _iand, _idiv, _idivmod, _ifloordiv, _ilshift, _imod, _imul, _in, _ior, _ipow, _irshift, _is, _isnot, _isub, _itruediv, _ixor, _jcall, _jcallexc, _jthrow, _le, _lshift, _lt, _mod, _mul, _ne, _notin, _or, _pow, _rshift, _sub, _truediv, _xor, asIndex, asIndex, asInt, asIterable, asLong, asName, asStringOrNull, asStringOrNull, bit_length, conjugate, delDict, delType, dispatch__init__, equals, fastGetClass, fastGetDict, getDict, getType, implementsDescrDelete, implementsDescrGet, implementsDescrSet, invoke, invoke, invoke, invoke, invoke, invoke, isCallable, isDataDescr, isIndex, isInteger, noAttributeError, object___subclasshook__, readonlyAttributeError, setDict, setType`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.lang.CharSequence

      `chars, codePoints`

- - ### Field Detail

    - #### TYPE

          public static final PyType TYPE

  - ### Constructor Detail

    - #### PyShadowString

          public PyShadowString()

      Empty string (not very useful but needed for technical reasons).

    - #### PyShadowString

          public PyShadowString(java.lang.String primary,
                                java.lang.String shadow)

      Construct an instance specifying primary and shadow values.

    - #### PyShadowString

          @Deprecated
          public PyShadowString(PyObject primary,
                                             java.lang.String shadow)

      Deprecated. use the constructor with strings instead.
      Construct an instance specifying primary and shadow values (bytes object expected for primary). This somewhat uncanonical constructor was removed in Jython 2.7.2. The deprecated version is kept for compatibility with JyNI 2.7-alpha5.

    - #### PyShadowString

          public PyShadowString(PyType subtype,
                                PyObject primary,
                                PyObject shadow)

  - ### Method Detail

    - #### getshadow

          public PyString getshadow()

      Get the shadow value.

    - #### shadowstr_getshadow

          public final PyString shadowstr_getshadow()

    - #### addTarget

          public void addTarget(java.lang.String className,
                                java.lang.String methodName)

      Specify a context (class, method) in which the shadow string is allowed to match.
      Parameters:
        `className` - class name to match or null to match anything.
        `methodName` - method name to match or null to match anything.

    - #### shadowstr_addtarget

          public final void shadowstr_addtarget(PyObject classname,
                                                PyObject methodname)

    - #### getTargets

          public PyList getTargets()

      Return a list of the tuples specifying the contexts in which the shadow value will be consulted during matching.

    - #### shadowstr_gettargets

          public final PyObject shadowstr_gettargets()

    - #### __eq__

          public PyObject __eq__(PyObject other)

      Compare this `PyShadowString` with another `PyObject` for equality. A `PyShadowString` is equal to the other object if its primary value is equal to it, or if its shadow value is equal to the other object and the test is made in one of its target contexts. (Two `PyShadowString` are equal if the primary values are equal, the primary of one matches the shadow of the other in the shadow's context, or their shadows match and both are in context.
      Overrides:
        `__eq__` in class `PyString`
      Parameters:
        `other` - to compare
      Returns:
        `PyBoolean` result (or `null` if not implemented)

    - #### __getslice__

          public PyObject __getslice__(PyObject start,
                                       PyObject stop,
                                       PyObject step)

      Overrides:
        `__getslice__` in class `PySequence`

    - #### startswith

          public boolean startswith(PyObject prefix)

      Description copied from class: `PyString`
      Equivalent to the Python `str.startswith` method testing whether a string starts with a specified prefix. `prefix` can also be a tuple of prefixes to look for.
      Overrides:
        `startswith` in class `PyString`
      Parameters:
        `prefix` - string to check for (or a `PyTuple` of them).
      Returns:
        `true` if this string slice starts with a specified prefix, otherwise `false`.

    - #### startswith

          public boolean startswith(PyObject prefix,
                                    PyObject start)

      Description copied from class: `PyString`
      Equivalent to the Python `str.startswith` method, testing whether a string starts with a specified prefix, where a sub-range is specified by `[start:]`. `start` is interpreted as in slice notation, with null or `Py.None` representing "missing". `prefix` can also be a tuple of prefixes to look for.
      Overrides:
        `startswith` in class `PyString`
      Parameters:
        `prefix` - string to check for (or a `PyTuple` of them).
        `start` - start of slice.
      Returns:
        `true` if this string slice starts with a specified prefix, otherwise `false`.

    - #### startswith

          public boolean startswith(PyObject prefix,
                                    PyObject start,
                                    PyObject end)

      Description copied from class: `PyString`
      Equivalent to the Python `str.startswith` method, testing whether a string starts with a specified prefix, where a sub-range is specified by `[start:end]`. Arguments `start` and `end` are interpreted as in slice notation, with null or `Py.None` representing "missing". `prefix` can also be a tuple of prefixes to look for.
      Overrides:
        `startswith` in class `PyString`
      Parameters:
        `prefix` - string to check for (or a `PyTuple` of them).
        `start` - start of slice.
        `end` - end of slice.
      Returns:
        `true` if this string slice starts with a specified prefix, otherwise `false`.

    - #### __repr__

          public PyString __repr__()

      Description copied from class: `PyObject`
      Equivalent to the standard Python `__repr__` method. Each sub-class of `PyObject` is likely to re-define this method to provide for its own reproduction.
      Overrides:
        `__repr__` in class `PyString`

Jython homepage