# The MIT License (MIT)
#
# Copyright (c) 2006-2011 Matthew Zipay <mattz@ninthtest.net>
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
"""This module defines a custom error type and several utility functions
used by Aglyph.
Aglyph is fully logged using the standard :mod:`logging` module, but by
default uses a no-op logging handler to suppress log messages. If you
want to enable Aglyph logging, define a logger for the *"aglyph"* log
channel in your application, **prior** to importing any Aglyph modules.
See :mod:`logging.config` for more information about configuring the
logging module.
"""
__author__ = "Matthew Zipay <mattz@ninthtest.net>"
# always the current version of Aglyph
__version__ = "1.1.0"
import logging
import platform
from aglyph.compat import (ClassAndFunctionTypes, log_23_compatibility,
NoOpLoggingHandler, python_implementation,
StringTypes)
__all__ = ["AglyphError", "format_dotted_name", "has_importable_dotted_name",
"identify_by_spec", "resolve_dotted_name"]
# define a logger for the "aglyph" channel to enable logging
_logger = logging.getLogger(__name__)
if (not _logger.handlers):
# suppress log messages by default
_logger.addHandler(NoOpLoggingHandler())
# log the Aglyph/Python versions and the platform (useful for debugging), and
# then the _23compat details
_logger.info("Aglyph %s; %s %s; %s" % (__version__, python_implementation,
platform.python_version(),
platform.platform()))
log_23_compatibility()
[docs]class AglyphError(Exception):
"""Raised when Aglyph operations fail with a condition that is not
sufficiently described by a built-in exception.
"""
[docs]def has_importable_dotted_name(obj):
"""Return ``True`` if *obj* is an importable class or unbound
function.
"""
return (isinstance(obj, ClassAndFunctionTypes) and
# need to look for __self__ because BuiltinFunctionType is the type
# of both built-in functions AND built-in methods
(getattr(obj, "__self__", None) is None))
[docs]def identify_by_spec(spec):
"""Return an identifier string for *spec*.
If *spec* is a string, it is returned. Otherwise, *spec* must be an
importable class or unbound function, and its dotted-name is
returned (see :func:`format_dotted_name`).
"""
if (isinstance(spec, StringTypes)):
return spec
else:
return format_dotted_name(spec)
[docs]def resolve_dotted_name(dotted_name):
"""Return the class or function identified by *dotted_name*.
*dotted_name* must be a "relative_module.identifier" string such
that the following production represents a valid import statement
with respect to the application's ``sys.path``:
.. productionlist::
import_stmt: "from" relative_module "import" identifier
This method is the inverse of :func:`format_dotted_name`.
:raises ImportError: if importing *dotted_name* fails
:raises ValueError: if *dotted_name* cannot be parsed into
"relative_module" and "identifier" parts
"""
_logger.debug("resolving %r", dotted_name)
try:
(module_name, identifier) = dotted_name.rsplit('.', 1)
module = __import__(module_name, globals(), locals(), [identifier])
return getattr(module, identifier)
except ImportError:
raise
except Exception:
raise ValueError("%r is not a valid dotted-name" % dotted_name)