########################################################################
# File name: structs.py
# This file is part of: aioxmpp
#
# LICENSE
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this program. If not, see
# .
#
########################################################################
"""
:mod:`~aioxmpp.structs` --- Simple data holders for common data types
#####################################################################
These classes provide a way to hold structured data which is commonly
encountered in the XMPP realm.
Stanza types
============
.. currentmodule:: aioxmpp
.. autoclass:: IQType
.. autoclass:: MessageType
.. autoclass:: PresenceType
.. autoclass:: ErrorType
Jabber IDs
==========
.. autoclass:: JID(localpart, domain, resource)
.. autofunction:: jid_escape
.. autofunction:: jid_unescape
Presence
========
.. autoclass:: PresenceShow
.. autoclass:: PresenceState
.. currentmodule:: aioxmpp.structs
Languages
=========
.. autoclass:: LanguageTag
.. autoclass:: LanguageRange
.. autoclass:: LanguageMap
Functions for working with language tags
----------------------------------------
.. autofunction:: basic_filter_languages
.. autofunction:: lookup_language
"""
import collections
import enum
import functools
import warnings
from .stringprep import nodeprep, resourceprep, nameprep
_USE_COMPAT_ENUM = True
class CompatibilityMixin:
def __hash__(self):
return hash(self.value)
def __eq__(self, other):
if not _USE_COMPAT_ENUM:
return super().__eq__(other)
if super().__eq__(other) is True:
return True
if self.value == other:
warnings.warn(
"as of aioxmpp 1.0, {} members will not compare equal to "
"their values".format(type(self).__name__),
DeprecationWarning,
stacklevel=2,
)
return True
return False
class ErrorType(CompatibilityMixin, enum.Enum):
"""
Enumeration for the :rfc:`6120` specified stanza error types.
These error types reflect are actually more reflecting the error classes,
but the attribute is called "type" nonetheless. For consistency, we are
calling it "type" here, too.
The following types are specified. The quotations in the member
descriptions are from :rfc:`6120`, Section 8.3.2.
.. attribute:: AUTH
The ``"auth"`` error type:
retry after providing credentials
When converted to an exception, it uses :exc:`~.XMPPAuthError`.
.. attribute:: CANCEL
The ``"cancel"`` error type:
do not retry (the error cannot be remedied)
When converted to an exception, it uses :exc:`~.XMPPCancelError`.
.. attribute:: CONTINUE
The ``"continue"`` error type:
proceed (the condition was only a warning)
When converted to an exception, it uses
:exc:`~.XMPPContinueError`.
.. attribute:: MODIFY
The ``"modify"`` error type:
retry after changing the data sent
When converted to an exception, it uses
:exc:`~.XMPPModifyError`.
.. attribute:: WAIT
The ``"wait"`` error type:
retry after waiting (the error is temporary)
When converted to an exception, it uses (guess what)
:exc:`~.XMPPWaitError`.
:class:`ErrorType` members compare and hash equal to their values. For
example::
assert ErrorType.CANCEL == "cancel"
assert "cancel" == ErrorType.CANCEL
assert hash(ErrorType.CANCEL) == hash("cancel")
.. deprecated:: 0.7
This behaviour will cease with aioxmpp 1.0, and the first assertion will
fail, the second may fail.
Please see the Changelog for :ref:`api-changelog-0.7` for further
details on how to upgrade your code efficiently.
"""
AUTH = "auth"
CANCEL = "cancel"
CONTINUE = "continue"
MODIFY = "modify"
WAIT = "wait"
class MessageType(CompatibilityMixin, enum.Enum):
"""
Enumeration for the :rfc:`6121` specified Message stanza types.
.. seealso::
:attr:`~.Message.type_`
Type attribute of Message stanzas.
Each member has the following meta-information:
.. autoattribute:: is_error
.. autoattribute:: is_request
.. autoattribute:: is_response
.. note::
The :attr:`is_error`, :attr:`is_request` and :attr:`is_response`
meta-information attributes share semantics across :class:`MessageType`,
:class:`PresenceType` and :class:`IQType`. You are encouraged to exploit
this in full duck-typing manner in generic stanza handling code.
The following types are specified. The quotations in the member
descriptions are from :rfc:`6121`, Section 5.2.2.
.. attribute:: NORMAL
The ``"normal"`` Message type:
The message is a standalone message that is sent outside the context
of a one-to-one conversation or groupchat, and to which it is
expected that the recipient will reply. Typically a receiving client
will present a message of type "normal" in an interface that enables
the recipient to reply, but without a conversation history. The
default value of the 'type' attribute is "normal".
Think of it as somewhat similar to "E-Mail via XMPP".
.. attribute:: CHAT
The ``"chat"`` Message type:
The message is sent in the context of a one-to-one chat session.
Typically an interactive client will present a message of type "chat"
in an interface that enables one-to-one chat between the two parties,
including an appropriate conversation history.
.. attribute:: GROUPCHAT
The ``"groupchat"`` Message type:
The message is sent in the context of a multi-user chat environment
[…]. Typically a receiving client will present a message of type
"groupchat" in an interface that enables many-to-many chat between
the parties, including a roster of parties in the chatroom and an
appropriate conversation history.
.. attribute:: HEADLINE
The ``"headline"`` Message type:
The message provides an alert, a notification, or other transient
information to which no reply is expected (e.g., news headlines,
sports updates, near-real-time market data, or syndicated content).
Because no reply to the message is expected, typically a receiving
client will present a message of type "headline" in an interface that
appropriately differentiates the message from standalone messages,
chat messages, and groupchat messages (e.g., by not providing the
recipient with the ability to reply).
Do not confuse this message type with the
:attr:`~.Message.subject` member of Messages!
.. attribute:: ERROR
The ``"error"`` Message type:
The message is generated by an entity that experiences an error when
processing a message received from another entity […]. A client that
receives a message of type "error" SHOULD present an appropriate
interface informing the original sender regarding the nature of the
error.
This is the only message type which is used in direct response to
another message, in the sense that the Stanza ID is preserved in the
response.
:class:`MessageType` members compare and hash equal to their values. For
example::
assert MessageType.CHAT == "chat"
assert "chat" == MessageType.CHAT
assert hash(MessageType.CHAT) == hash("chat")
.. deprecated:: 0.7
This behaviour will cease with aioxmpp 1.0, and the first assertion will
fail, the second may fail.
Please see the Changelog for :ref:`api-changelog-0.7` for further
details on how to upgrade your code efficiently.
"""
NORMAL = "normal"
CHAT = "chat"
GROUPCHAT = "groupchat"
HEADLINE = "headline"
ERROR = "error"
@property
def is_error(self):
"""
True for the :attr:`ERROR` type, false for all others.
"""
return self == MessageType.ERROR
@property
def is_response(self):
"""
True for the :attr:`ERROR` type, false for all others.
This is intended. Request/Response semantics do not really apply for
messages, except that errors are generally in response to other
messages.
"""
return self == MessageType.ERROR
@property
def is_request(self):
"""
False. See :attr:`is_response`.
"""
return False
class PresenceType(CompatibilityMixin, enum.Enum):
"""
Enumeration for the :rfc:`6121` specified Presence stanza types.
.. seealso::
:attr:`~.Presence.type_`
Type attribute of Presence stanzas.
Each member has the following meta-information:
.. autoattribute:: is_error
.. autoattribute:: is_request
.. autoattribute:: is_response
.. autoattribute:: is_presence_state
.. note::
The :attr:`is_error`, :attr:`is_request` and :attr:`is_response`
meta-information attributes share semantics across :class:`MessageType`,
:class:`PresenceType` and :class:`IQType`. You are encouraged to exploit
this in full duck-typing manner in generic stanza handling code.
The following types are specified. The quotes in the member descriptions
are from :rfc:`6121`, Section 4.7.1.
.. attribute:: ERROR
The ``"error"`` Presence type:
An error has occurred regarding processing of a previously sent
presence stanza; if the presence stanza is of type "error", it MUST
include an child element […].
This is the only presence stanza type which is used in direct response
to another presence stanza, in the sense that the Stanza ID is preserved
in the response.
In addition, :attr:`ERROR` presence stanzas may be seen during presence
broadcast if inter-server communication fails.
.. attribute:: PROBE
The ``"probe"`` Presence type:
A request for an entity's current presence; SHOULD be generated only
by a server on behalf of a user.
This should not be seen in client code.
.. attribute:: SUBSCRIBE
The ``"subscribe"`` Presence type:
The sender wishes to subscribe to the recipient's presence.
.. attribute:: SUBSCRIBED
The ``"subscribed"`` Presence type:
The sender has allowed the recipient to receive their presence.
.. attribute:: UNSUBSCRIBE
The ``"unsubscribe"`` Presence type:
The sender is unsubscribing from the receiver's presence.
.. attribute:: UNSUBSCRIBED
The ``"unsubscribed"`` Presence type:
The subscription request has been denied or a previously granted
subscription has been canceled.
.. attribute:: AVAILABLE
The Presence type signalled with an absent type attribute:
The absence of a 'type' attribute signals that the relevant entity is
available for communication […].
.. attribute:: UNAVAILABLE
The ``"unavailable"`` Presence type:
The sender is no longer available for communication.
:class:`PresenceType` members compare and hash equal to their values. For
example::
assert PresenceType.PROBE == "probe"
assert "probe" == PresenceType.PROBE
assert hash(PresenceType.PROBE) == hash("probe")
.. deprecated:: 0.7
This behaviour will cease with aioxmpp 1.0, and the first assertion will
fail, the second may fail.
Please see the Changelog for :ref:`api-changelog-0.7` for further
details on how to upgrade your code efficiently.
"""
ERROR = "error"
PROBE = "probe"
SUBSCRIBE = "subscribe"
SUBSCRIBED = "subscribed"
UNAVAILABLE = "unavailable"
UNSUBSCRIBE = "unsubscribe"
UNSUBSCRIBED = "unsubscribed"
AVAILABLE = None
@property
def is_error(self):
"""
True for the :attr:`ERROR` type, false otherwise.
"""
return self == PresenceType.ERROR
@property
def is_response(self):
"""
True for the :attr:`ERROR` type, false otherwise.
This is intended. Request/Response semantics do not really apply for
presence stanzas, except that errors are generally in response to other
presence stanzas.
"""
return self == PresenceType.ERROR
@property
def is_request(self):
"""
False. See :attr:`is_response`.
"""
return False
@property
def is_presence_state(self):
"""
True for the :attr:`AVAILABLE` and :attr:`UNAVAILABLE` types, false
otherwise.
Useful to discern presence state notifications from meta-stanzas
regarding presence broadcast control.
"""
return (self == PresenceType.AVAILABLE or
self == PresenceType.UNAVAILABLE)
class IQType(CompatibilityMixin, enum.Enum):
"""
Enumeration for the :rfc:`6120` specified IQ stanza types.
.. seealso::
:attr:`~.IQ.type_`
Type attribute of IQ stanzas.
Each member has the following meta-information:
.. autoattribute:: is_error
.. autoattribute:: is_request
.. autoattribute:: is_response
.. note::
The :attr:`is_error`, :attr:`is_request` and :attr:`is_response`
meta-information attributes share semantics across :class:`MessageType`,
:class:`PresenceType` and :class:`IQType`. You are encouraged to exploit
this in full duck-typing manner in generic stanza handling code.
The following types are specified. The quotations in the member
descriptions are from :rfc:`6120`, Section 8.2.3.
.. attribute:: GET
The ``"get"`` IQ type:
The stanza requests information, inquires about what
data is needed in order to complete further operations, etc.
A :attr:`GET` IQ must contain a payload, via the
:attr:`~.IQ.payload` attribute.
.. attribute:: SET
The ``"set"`` IQ type:
The stanza provides data that is needed for an operation to be
completed, sets new values, replaces existing values, etc.
A :attr:`SET` IQ must contain a payload, via the
:attr:`~.IQ.payload` attribute.
.. attribute:: ERROR
The ``"error"`` IQ type:
The stanza reports an error that has occurred regarding processing
or delivery of a get or set request[…].
:class:`~.IQ` objects carrying the :attr:`ERROR` type usually
have the :attr:`~.IQ.error` set to a :class:`~.stanza.Error`
instance describing the details of the error.
The :attr:`~.IQ.payload` attribute may also be set if the sender
of the :attr:`ERROR` was kind enough to include the data which caused
the problem.
.. attribute:: RESULT
The ``"result"`` IQ type:
The stanza is a response to a successful get or set request.
A :attr:`RESULT` IQ may contain a payload with more data.
:class:`IQType` members compare and hash equal to their values. For
example::
assert IQType.GET == "get"
assert "get" == IQType.GET
assert hash(IQType.GET) == hash("get")
.. deprecated:: 0.7
This behaviour will cease with aioxmpp 1.0, and the first assertion will
fail, the second may fail.
Please see the Changelog for :ref:`api-changelog-0.7` for further
details on how to upgrade your code efficiently.
"""
GET = "get"
SET = "set"
ERROR = "error"
RESULT = "result"
@property
def is_error(self):
"""
True for the :attr:`ERROR` type, false otherwise.
"""
return self == IQType.ERROR
@property
def is_request(self):
"""
True for request types (:attr:`GET` and :attr:`SET`), false otherwise.
"""
return self == IQType.GET or self == IQType.SET
@property
def is_response(self):
"""
True for the response types (:attr:`RESULT` and :attr:`ERROR`), false
otherwise.
"""
return self == IQType.RESULT or self == IQType.ERROR
class JID(collections.namedtuple("JID", ["localpart", "domain", "resource"])):
"""
Represent a :term:`Jabber ID (JID) `.
To construct a :class:`JID`, either use the actual constructor, or use the
:meth:`fromstr` class method.
:param localpart: The part in front of the ``@`` of the JID, or
:data:`None` if the localpart shall be omitted (which is different from
it being empty, which would be invalid).
:type localpart: :class:`str` or :data:`None`
:param domain: The domain of the JID. This is the only mandatory part of
a JID.
:type domain: :class:`str`
:param resource: The resource part of the JID or :data:`None` to omit the
resource part.
:type resource: :class:`str` or :data:`None`
:param strict: Enable strict validation
:type strict: :class:`bool`
:raises ValueError: if the JID composed of the given parts is invalid
Construct a JID out of its parts. It validates the parts individually, as
well as the JID as a whole.
If `strict` is false, unassigned codepoints are allowed in any of the parts
of the JID. In the future, other deviations from the respective stringprep
profiles may be allowed, too.
The idea is to use non-`strict` when output is received from outside and
when it is reflected, following the old principle "be conservative in what
you send and liberal in what you receive". Otherwise, strict checking
should be enabled. This brings maximum interoperability.
.. automethod:: fromstr
Information about a JID:
.. attribute:: localpart
The localpart, stringprep’d from the argument to the constructor.
.. attribute:: domain
The domain, stringprep’d from the argument to the constructor.
.. attribute:: resource
The resource, stringprep’d from the argument to the constructor.
.. autoattribute:: is_bare
.. autoattribute:: is_domain
:class:`JID` objects are immutable. To obtain a JID object with a changed
property, use one of the following methods:
.. automethod:: bare
.. automethod:: replace(*, [localpart], [domain], [resource])
"""
__slots__ = []
def __new__(cls, localpart, domain, resource, *, strict=True):
if localpart:
localpart = nodeprep(
localpart,
allow_unassigned=not strict
)
if domain is not None:
domain = nameprep(
domain,
allow_unassigned=not strict
)
if resource:
resource = resourceprep(
resource,
allow_unassigned=not strict
)
if not domain:
raise ValueError("domain must not be empty or None")
if len(domain.encode("utf-8")) > 1023:
raise ValueError("domain too long")
if localpart is not None:
if not localpart:
raise ValueError("localpart must not be empty")
if len(localpart.encode("utf-8")) > 1023:
raise ValueError("localpart too long")
if resource is not None:
if not resource:
raise ValueError("resource must not be empty")
if len(resource.encode("utf-8")) > 1023:
raise ValueError("resource too long")
return super().__new__(cls, localpart, domain, resource)
def replace(self, **kwargs):
"""
Construct a new :class:`JID` object, using the values of the current
JID. Use the arguments to override specific attributes on the new
object.
All arguments are keyword arguments.
:param localpart: Set the local part of the resulting JID.
:param domain: Set the domain of the resulting JID.
:param resource: Set the resource part of the resulting JID.
:raises: See :class:`JID`
:return: A new :class:`JID` object with the corresponding
substitutions performed.
:rtype: :class:`JID`
The attributes of parameters which are omitted are not modified and
copied down to the result.
"""
new_kwargs = {}
strict = kwargs.pop("strict", True)
try:
localpart = kwargs.pop("localpart")
except KeyError:
pass
else:
if localpart:
localpart = nodeprep(
localpart,
allow_unassigned=not strict
)
new_kwargs["localpart"] = localpart
try:
domain = kwargs.pop("domain")
except KeyError:
pass
else:
if not domain:
raise ValueError("domain must not be empty or None")
new_kwargs["domain"] = nameprep(
domain,
allow_unassigned=not strict
)
try:
resource = kwargs.pop("resource")
except KeyError:
pass
else:
if resource:
resource = resourceprep(
resource,
allow_unassigned=not strict
)
new_kwargs["resource"] = resource
if kwargs:
raise TypeError("replace() got an unexpected keyword argument"
" {!r}".format(
next(iter(kwargs))))
return super()._replace(**new_kwargs)
def __str__(self):
result = self.domain
if self.localpart:
result = self.localpart + "@" + result
if self.resource:
result += "/" + self.resource
return result
def bare(self):
"""
Create a copy of the :class:`JID` which is bare.
:return: This JID with the :attr:`resource` set to :data:`None`.
:rtype: :class:`JID`
Return the bare version of this JID as new :class:`JID` object.
"""
return self.replace(resource=None)
@property
def is_bare(self):
"""
:data:`True` if the JID is bare, i.e. has an empty :attr:`resource`
part.
"""
return not self.resource
@property
def is_domain(self):
"""
:data:`True` if the JID is a domain, i.e. if both the :attr:`localpart`
and the :attr:`resource` are empty.
"""
return not self.resource and not self.localpart
@classmethod
def fromstr(cls, s, *, strict=True):
"""
Construct a JID out of a string containing it.
:param s: The string to parse.
:type s: :class:`str`
:param strict: Whether to enable strict parsing.
:type strict: :class:`bool`
:raises: See :class:`JID`
:return: The parsed JID
:rtype: :class:`JID`
See the :class:`JID` class level documentation for the semantics of
`strict`.
"""
nodedomain, sep, resource = s.partition("/")
if not sep:
resource = None
localpart, sep, domain = nodedomain.partition("@")
if not sep:
domain = localpart
localpart = None
return cls(localpart, domain, resource, strict=strict)
@functools.total_ordering
class PresenceShow(CompatibilityMixin, enum.Enum):
"""
Enumeration to support the ``show`` element of presence stanzas.
The enumeration members support total ordering. The order is defined by
relevance and is the following (from lesser to greater): :attr:`XA`,
:attr:`AWAY`, :attr:`NONE`, :attr:`CHAT`, :attr:`DND`. The order is
intended to be used to extract the most relevant resource e.g. in a roster.
.. versionadded:: 0.8
.. attribute:: XA
:annotation: = "xa"
.. epigraph::
The entity or resource is away for an extended period (xa = "eXtended
Away").
-- :rfc:`6121`, Section 4.7.2.1
.. attribute:: EXTENDED_AWAY
:annotation: = "xa"
Alias to :attr:`XA`.
.. attribute:: AWAY
:annotation: = "away"
.. epigraph::
The entity or resource is temporarily away.
-- :rfc:`6121`, Section 4.7.2.1
.. attribute:: NONE
:annotation: = None
Signifies absence of the ``show`` element.
.. attribute:: PLAIN
:annotation: = None
Alias to :attr:`NONE`.
.. attribute:: CHAT
:annotation: = "chat"
.. epigraph::
The entity or resource is actively interested in chatting.
-- :rfc:`6121`, Section 4.7.2.1
.. attribute:: FREE_FOR_CHAT
:annotation: = "chat"
Alias to :attr:`CHAT`.
.. attribute:: DND
:annotation: = "dnd"
.. epigraph::
The entity or resource is busy (dnd = "Do Not Disturb").
-- :rfc:`6121`, Section 4.7.2.1
.. attribute:: DO_NOT_DISTURB
:annotation: = "dnd"
Alias to :attr:`DND`.
"""
XA = "xa"
EXTENDED_AWAY = "xa"
AWAY = "away"
NONE = None
PLAIN = None
CHAT = "chat"
FREE_FOR_CHAT = "chat"
DND = "dnd"
DO_NOT_DISTURB = "dnd"
def __lt__(self, other):
try:
w1 = self._WEIGHTS[self]
w2 = self._WEIGHTS[other]
except KeyError:
return NotImplemented
return w1 < w2
PresenceShow._WEIGHTS = {
PresenceShow.XA: -2,
PresenceShow.AWAY: -1,
PresenceShow.NONE: 0,
PresenceShow.CHAT: 1,
PresenceShow.DND: 2,
}
@functools.total_ordering
class PresenceState:
"""
Hold a presence state of an XMPP resource, as defined by the presence
stanza semantics.
`available` must be a boolean value, which defines whether the resource is
available or not. If the resource is available, `show` may be set to one of
``"dnd"``, ``"xa"``, ``"away"``, :data:`None`, ``"chat"`` (it is a
:class:`ValueError` to attempt to set `show` to a non-:data:`None` value if
`available` is false).
:class:`PresenceState` objects are ordered by their availability and by
their show values. Non-availability sorts lower than availability, and for
available presence states the order is in the order of valid values given
for the `show` above.
.. attribute:: available
As per the argument to the constructor, converted to a :class:`bool`.
.. attribute:: show
As per the argument to the constructor.
.. automethod:: apply_to_stanza
.. automethod:: from_stanza
:class:`PresenceState` objects are immutable.
"""
__slots__ = ["_available", "_show"]
def __init__(self, available=False, show=PresenceShow.NONE):
super().__init__()
if not available and show != PresenceShow.NONE:
raise ValueError("Unavailable state cannot have show value")
if not isinstance(show, PresenceShow):
try:
show = PresenceShow(show)
except ValueError:
raise ValueError("Not a valid show value") from None
else:
warnings.warn(
"as of aioxmpp 1.0, the show argument must use "
"PresenceShow instead of str",
DeprecationWarning,
stacklevel=2
)
self._available = bool(available)
self._show = show
@property
def available(self):
return self._available
@property
def show(self):
return self._show
def __lt__(self, other):
my_key = (self.available, self.show)
try:
other_key = (other.available, other.show)
except AttributeError:
return NotImplemented
return my_key < other_key
def __eq__(self, other):
try:
return (self.available == other.available and
self.show == other.show)
except AttributeError:
return NotImplemented
def __repr__(self):
more = ""
if self.available:
if self.show != PresenceShow.NONE:
more = " available show={!r}".format(self.show)
else:
more = " available"
return "".format(more)
def apply_to_stanza(self, stanza_obj):
"""
Apply the properties of this :class:`PresenceState` to a
:class:`~aioxmpp.Presence` `stanza_obj`. The
:attr:`~aioxmpp.Presence.type_` and
:attr:`~aioxmpp.Presence.show` attributes of the object will be
modified to fit the values in this object.
"""
if self.available:
stanza_obj.type_ = PresenceType.AVAILABLE
else:
stanza_obj.type_ = PresenceType.UNAVAILABLE
stanza_obj.show = self.show
@classmethod
def from_stanza(cls, stanza_obj, strict=False):
"""
Create and return a new :class:`PresenceState` object which inherits
the presence state as advertised in the given
:class:`~aioxmpp.Presence` stanza.
If `strict` is :data:`True`, the value of `show` is strictly checked,
that is, it is required to be :data:`None` if the stanza indicates an
unavailable state.
The default is not to check this.
"""
if not stanza_obj.type_.is_presence_state:
raise ValueError("presence state stanza required")
available = stanza_obj.type_ == PresenceType.AVAILABLE
if not strict:
show = stanza_obj.show if available else PresenceShow.NONE
else:
show = stanza_obj.show
return cls(available=available, show=show)
@functools.total_ordering
class LanguageTag:
"""
Implementation of a language tag. This may be a fully RFC5646 compliant
implementation some day, but for now it is only very simplistic stub.
There is no input validation of any kind.
:class:`LanguageTag` instances compare and hash case-insensitively.
.. automethod:: fromstr
.. autoattribute:: match_str
.. autoattribute:: print_str
"""
__slots__ = ("_tag",)
def __init__(self, *, tag=None):
if not tag:
raise ValueError("tag cannot be empty")
self._tag = tag
@property
def match_str(self):
"""
The string which is used for matching two lanugage tags. This is the
lower-cased version of the :attr:`print_str`.
"""
return self._tag.lower()
@property
def print_str(self):
"""
The stringified language tag.
"""
return self._tag
@classmethod
def fromstr(cls, s):
"""
Create a language tag from the given string `s`.
.. note::
This is a stub implementation which merely refers to the given
string as the :attr:`print_str` and derives the :attr:`match_str`
from that.
"""
return cls(tag=s)
def __str__(self):
return self.print_str
def __eq__(self, other):
try:
return self.match_str == other.match_str
except AttributeError:
return False
def __lt__(self, other):
try:
return self.match_str < other.match_str
except AttributeError:
return NotImplemented
def __le__(self, other):
try:
return self.match_str <= other.match_str
except AttributeError:
return NotImplemented
def __hash__(self):
return hash(self.match_str)
def __repr__(self):
return "<{}.{}.fromstr({!r})>".format(
type(self).__module__,
type(self).__qualname__,
str(self))
class LanguageRange:
"""
Implementation of a language range. This may be a fully RFC4647 compliant
implementation some day, but for now it is only very simplistic stub.
There is no input validation of any kind.
:class:`LanguageRange` instances compare and hash case-insensitively.
.. automethod:: fromstr
.. automethod:: strip_rightmost
.. autoattribute:: match_str
.. autoattribute:: print_str
"""
__slots__ = ("_tag",)
def __init__(self, *, tag=None):
if not tag:
raise ValueError("range cannot be empty")
self._tag = tag
@property
def match_str(self):
"""
The string which is used for matching two lanugage tags. This is the
lower-cased version of the :attr:`print_str`.
"""
return self._tag.lower()
@property
def print_str(self):
"""
The stringified language tag.
"""
return self._tag
@classmethod
def fromstr(cls, s):
"""
Create a language tag from the given string `s`.
.. note::
This is a stub implementation which merely refers to the given
string as the :attr:`print_str` and derives the :attr:`match_str`
from that.
"""
if s == "*":
return cls.WILDCARD
return cls(tag=s)
def __str__(self):
return self.print_str
def __eq__(self, other):
try:
return self.match_str == other.match_str
except AttributeError:
return False
def __hash__(self):
return hash(self.match_str)
def __repr__(self):
return "<{}.{}.fromstr({!r})>".format(
type(self).__module__,
type(self).__qualname__,
str(self))
def strip_rightmost(self):
"""
Strip the rightmost part of the language range. If the new rightmost
part is a singleton or ``x`` (i.e. starts an extension or private use
part), it is also stripped.
Return the newly created :class:`LanguageRange`.
"""
parts = self.print_str.split("-")
parts.pop()
if parts and len(parts[-1]) == 1:
parts.pop()
return type(self).fromstr("-".join(parts))
LanguageRange.WILDCARD = LanguageRange(tag="*")
def basic_filter_languages(languages, ranges):
"""
Filter languages using the string-based basic filter algorithm described in
RFC4647.
`languages` must be a sequence of :class:`LanguageTag` instances which are
to be filtered.
`ranges` must be an iterable which represent the basic language ranges to
filter with, in priority order. The language ranges must be given as
:class:`LanguageRange` objects.
Return an iterator of languages which matched any of the `ranges`. The
sequence produced by the iterator is in match order and duplicate-free. The
first range to match a language yields the language into the iterator, no
other range can yield that language afterwards.
"""
if LanguageRange.WILDCARD in ranges:
yield from languages
return
found = set()
for language_range in ranges:
range_str = language_range.match_str
for language in languages:
if language in found:
continue
match_str = language.match_str
if match_str == range_str:
yield language
found.add(language)
continue
if len(range_str) < len(match_str):
if (match_str[:len(range_str)] == range_str and
match_str[len(range_str)] == "-"):
yield language
found.add(language)
continue
def lookup_language(languages, ranges):
"""
Look up a single language in the sequence `languages` using the lookup
mechansim described in RFC4647. If no match is found, :data:`None` is
returned. Otherwise, the first matching language is returned.
`languages` must be a sequence of :class:`LanguageTag` objects, while
`ranges` must be an iterable of :class:`LanguageRange` objects.
"""
for language_range in ranges:
while True:
try:
return next(iter(basic_filter_languages(
languages,
[language_range])))
except StopIteration:
pass
try:
language_range = language_range.strip_rightmost()
except ValueError:
break
class LanguageMap(dict):
"""
A :class:`dict` subclass specialized for holding :class:`LanugageTag`
instances as keys.
In addition to the interface provided by :class:`dict`, instances of this
class also have the following methods:
.. automethod:: lookup
.. automethod:: any
"""
def lookup(self, language_ranges):
"""
Perform an RFC4647 language range lookup on the keys in the
dictionary. `language_ranges` must be a sequence of
:class:`LanguageRange` instances.
Return the entry in the dictionary with a key as produced by
`lookup_language`. If `lookup_language` does not find a match and the
mapping contains an entry with key :data:`None`, that entry is
returned, otherwise :class:`KeyError` is raised.
"""
keys = list(self.keys())
try:
keys.remove(None)
except ValueError:
pass
keys.sort()
key = lookup_language(keys, language_ranges)
return self[key]
def any(self):
"""
Returns any element from the language map, preferring the :data:`None`
key if it is available.
Guarantees to always return the same element for a map with the same
keys, even if the keys are iterated over in a different order.
"""
if not self:
raise ValueError("any() on empty map")
try:
return self[None]
except KeyError:
return self[min(self)]
# \ is treated specially because it is only escaped if followed by a valid
# escape sequence... that is so weird.
ESCAPABLE_CODEPOINTS = " \"&'/:<>@"
def jid_escape(s):
"""
Return an escaped version of a string for use in a JID localpart.
.. seealso::
:func:`jid_unescape`
for the reverse transformation
:param s: The string to escape for use as localpart.
:type s: :class:`str`
:raise ValueError: If the string starts or ends with a space.
:return: The escaped string.
:rtype: :class:`str`
.. note::
JID Escaping does not allow embedding arbitrary characters in the
localpart. Only a defined subset of characters can be escaped.
Refer to :xep:`0106` for details.
.. note::
No validity check is made on the result. It is assumed that the
result is passed to the :class:`JID` constructor, which will
perform validity checks on its own.
"""
# we first escape all backslashes which need to be escaped
for cp in "\\" + ESCAPABLE_CODEPOINTS:
seq = "\\{:02x}".format(ord(cp))
s = s.replace(seq, "\\5c{:02x}".format(ord(cp)))
# now we escape all the other stuff
for cp in ESCAPABLE_CODEPOINTS:
s = s.replace(cp, "\\{:02x}".format(ord(cp)))
return s
def jid_unescape(localpart):
"""
Un-escape a JID Escaped localpart.
.. seealso::
:func:`jid_escape`
for the reverse transformation
:param localpart: The escaped localpart
:type localpart: :class:`str`
:return: The unescaped localpart.
:rtype: :class:`str`
.. note::
JID Escaping does not allow embedding arbitrary characters in the
localpart. Only a defined subset of characters can be escaped.
Refer to :xep:`0106` for details.
"""
s = localpart
for cp in ESCAPABLE_CODEPOINTS:
s = s.replace("\\{:02x}".format(ord(cp)), cp)
for cp in ESCAPABLE_CODEPOINTS + "\\":
s = s.replace(
"\\5c{:02x}".format(ord(cp)),
"\\{:02x}".format(ord(cp)),
)
return s