Merge pull request #18 from Princeton-CDH/chore/17-revert-xmlmap

Export names from the top level of `xmlmap` (#17)

Author: blms

MIGRATION.rst

@@ -1,50 +1,8 @@
 Migration from ``eulxml``
 -------------------------
 
-A convenience script called ``migrate-eulxml`` has been included in order
-to migrate your project from ``eulxml`` to ``neuxml``, which will replace
-any usage of the package name in all ``.py`` files in the passed directory
-and subdirectories. After upgrading to Python 3.10+ and installing the
-updated package, you can run the script::
-
-    migrate-eulxml /path/to/your/project
-
-Or you can run the script directly without installing the package::
-
-    python neuxml/utils/migrate_eulxml.py /path/to/your/project
-
-In addition to renaming the package from ``eulxml`` to ``neuxml``, the usage
-of indirect imports from ``neuxml.xmlmap`` has been removed, and definitions
-must be imported directly from its submodules instead. The migration script
-will also attempt to make these changes automatically, but may not work in
-all cases, so be sure to check your imports manually as well.
-
-For example, imports have changed from this style:
-
-.. code-block:: python
-
-    from neuxml import xmlmap
-
-    xmlmap.XmlObject
-    xmlmap.Field
-
-to this style:
-
-.. code-block:: python
-
-    from neuxml.xmlmap import core, fields
-
-    core.XmlObject
-    fields.Field
-
-Class and function imports are also acceptable (e.g. ``from neuxml.xmlmap.core
-import XmlObject``).
-
-----
-
-If you would like to automatically replace all instances of ``eulxml`` with
-``neuxml`` but otherwise complete the import migration manually, you may use
-the following one-line shell script. 
+To ease migration by automatically replacing all instances of ``eulxml`` with
+``neuxml``, you may use the following one-line shell script. 
 
 On MacOS:
 

README.rst

@@ -21,7 +21,7 @@ python classes to access, update, and create XML content as standard Python type
 
 **neuxml.xmlmap** makes it possible to map XML content to Python objects in a
 pythonic and object-oriented way, which is easier to use than typical DOM access.
-With the `neuxml.xmlmap.core.XmlObject` class, XML can be read, modified, and even
+With the `neuxml.xmlmap.XmlObject` class, XML can be read, modified, and even
 created from scratch in some cases, as long as the configured XPath can
 be used to construct new nodes.
 

doc/index.rst

@@ -4,7 +4,7 @@ neuxml
 neuxml is an extensible library for reading and writing XML documents in
 idiomatic Python. It allows developers to `map predictable XML node
 structures <xmlmap.html#general-usage>`_ to
-:class:`~neuxml.xmlmap.core.XmlObject` subclasses, using field definitions to map
+:class:`~neuxml.xmlmap.XmlObject` subclasses, using field definitions to map
 `XPath <http://www.w3.org/TR/xpath/>`_ expressions directly to Python
 attributes. neuxml also includes an XPath parser in :mod:`neuxml.xpath`.
 

doc/xmlmap.rst

@@ -44,18 +44,18 @@ Python integer and the second ``<baz>`` as a string value. We also want to
 access all of them (there may be lots on another ``<foo>``) as a big list of
 integers. We can create an object to map these fields like this::
 
-   from neuxml.xmlmap import core, fields
+   from neuxml import xmlmap
 
-   class Foo(core.XmlObject):
-       first_baz = fields.IntegerField('bar[1]/baz')
-       second_baz = fields.StringField('bar[2]/baz')
-       qux = fields.StringListField('qux')
+   class Foo(xmlmap.XmlObject):
+       first_baz = xmlmap.IntegerField('bar[1]/baz')
+       second_baz = xmlmap.StringField('bar[2]/baz')
+       qux = xmlmap.StringListField('qux')
    
 :attr:`first_baz`, :attr:`second_baz`, and :attr:`all_baz` here are
 attributes of the :class:`Foo` object. We can access them in later code like
 this::
 
-   >>> foo = xmlmap.core.load_xmlobject_from_file(foo_path, xmlclass=Foo)
+   >>> foo = xmlmap.load_xmlobject_from_file(foo_path, xmlclass=Foo)
    >>> foo.first_baz
    42
    >>> foo.second_baz
@@ -82,7 +82,7 @@ Concepts
 --------
 
 :mod:`~neuxml.xmlmap` simplifies access to XML data in Python. Programs
-can define new :class:`~neuxml.xmlmap.core.XmlObject` subclasses representing a
+can define new :class:`~neuxml.xmlmap.XmlObject` subclasses representing a
 type of XML node with predictable structure. Members of these classes can be
 regular methods and values like in regular Python classes, but they can also be
 special :ref:`field <xmlmap-field>` objects that associate XPath expressions
@@ -128,7 +128,7 @@ whole collection of them.
 Field objects are typically created as part of an :class:`XmlObject`
 definition and accessed with standard Python object attribute syntax. If a
 :class:`Foo` class defines a :attr:`bar` attribute as an
-:mod:`~neuxml.xmlmap.fields` field object, then an object will reference it simply
+:mod:`~neuxml.xmlmap` field object, then an object will reference it simply
 as ``foo.bar``.
 
 .. automodule:: neuxml.xmlmap.fields
@@ -138,12 +138,12 @@ as ``foo.bar``.
 Other facilities
 ----------------
 
-.. autofunction:: neuxml.xmlmap.core.load_xmlobject_from_string
+.. autofunction:: neuxml.xmlmap.load_xmlobject_from_string
 
-.. autofunction:: neuxml.xmlmap.core.load_xmlobject_from_file
+.. autofunction:: neuxml.xmlmap.load_xmlobject_from_file
 
-.. autofunction:: neuxml.xmlmap.core.parseString
+.. autofunction:: neuxml.xmlmap.parseString
 
-.. autofunction:: neuxml.xmlmap.core.parseUri
+.. autofunction:: neuxml.xmlmap.parseUri
 
-.. autofunction:: neuxml.xmlmap.core.loadSchema(uri, base_uri=None)
+.. autofunction:: neuxml.xmlmap.loadSchema(uri, base_uri=None)

neuxml/catalog.py

@@ -35,7 +35,7 @@
 import sys
 
 import neuxml
-from neuxml.xmlmap import core, fields
+from neuxml import xmlmap
 
 # requests is an optional dependency, handle gracefully if not present
 try:
@@ -74,25 +74,25 @@
 # 'http://www.openarchives.org/OAI/2.0/oai_dc.xsd',
 
 
-class Uri(core.XmlObject):
-    """:class:`core.XmlObject` class for Catalog URIs"""
+class Uri(xmlmap.XmlObject):
+    """:class:`xmlmap.XmlObject` class for Catalog URIs"""
 
     ROOT_NAME = "uri"
     ROOT_NS = "urn:oasis:names:tc:entity:xmlns:xml:catalog"
     #: name, i.e. schema URI
-    name = fields.StringField("@name")
+    name = xmlmap.StringField("@name")
     #: uri, i.e. path to load the schema locally
-    uri = fields.StringField("@uri")
+    uri = xmlmap.StringField("@uri")
 
 
-class Catalog(core.XmlObject):
-    """:class:`core.XmlObject` class to for generating XML Catalogs"""
+class Catalog(xmlmap.XmlObject):
+    """:class:`xmlmap.XmlObject` class to for generating XML Catalogs"""
 
     ROOT_NAME = "catalog"
     ROOT_NS = "urn:oasis:names:tc:entity:xmlns:xml:catalog"
     ROOT_NAMESPACES = {"c": ROOT_NS}
     #: list of uris, as instance of :class:`Uri`
-    uri_list = fields.NodeListField("c:uri", Uri)
+    uri_list = xmlmap.NodeListField("c:uri", Uri)
 
 
 def download_schema(uri, path, comment=None):

neuxml/utils/migrate_eulxml.py

@@ -20,18 +20,70 @@
 nodes map to Python attributes using XPath expressions.
 
 For developer convenience this package is divided into submodules. Users
-should import the names from submodules. This package exports
+should import the names directly from neuxml.xmlmap. This package exports
 the following names:
- * core.XmlObject -- a base class for XML-Python mapping objects
- * core.parseUri and core.parseString -- parse a URI or string into an xml node with
+ * XmlObject -- a base class for XML-Python mapping objects
+ * parseUri and parseString -- parse a URI or string into an xml node with
    XPath methods that xmlmap depends on
- * core.load_xmlobject_from_string and core.load_xmlobject_from_file -- parse a string
+ * load_xmlobject_from_string and load_xmlobject_from_file -- parse a string
    or file directly into an XmlObject
- * fields.NodeField and fields.NodeListField -- field classes for mapping relative
+ * NodeField and NodeListField -- field classes for mapping relative
    xml nodes to other XmlObjects
- * fields.StringField and fields.StringListField -- field classes for mapping xml
+ * StringField and StringListField -- field classes for mapping xml
    nodes to Python strings
- * fields.IntegerField and fields.IntegerListField -- field classes for mapping xml
+ * IntegerField and IntegerListField -- field classes for mapping xml
    nodes to Python integers
 
 """
+
+from neuxml.xmlmap.core import (
+    XmlObject,
+    parseUri,
+    parseString,
+    loadSchema,
+    load_xmlobject_from_string,
+    load_xmlobject_from_file,
+    load_xslt,
+)
+from neuxml.xmlmap.fields import (
+    StringField,
+    StringListField,
+    IntegerField,
+    IntegerListField,
+    NodeField,
+    NodeListField,
+    ItemField,
+    SimpleBooleanField,
+    DateTimeField,
+    DateTimeListField,
+    DateField,
+    DateListField,
+    SchemaField,
+    FloatField,
+    FloatListField,
+)
+
+__all__ = [
+    "XmlObject",
+    "parseUri",
+    "parseString",
+    "loadSchema",
+    "load_xmlobject_from_string",
+    "load_xmlobject_from_file",
+    "load_xslt",
+    "StringField",
+    "StringListField",
+    "IntegerField",
+    "IntegerListField",
+    "NodeField",
+    "NodeListField",
+    "ItemField",
+    "SimpleBooleanField",
+    "DateTimeField",
+    "DateTimeListField",
+    "DateField",
+    "DateListField",
+    "SchemaField",
+    "FloatField",
+    "FloatListField",
+]