Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Getting ready for PyPI distribution

- Added (not yet tested) setup.py script.
- Switched to reStructuredText for README, as this is supported by both
  github and PyPI.
- Added copy of Apache License version 2.0 boilerplate in LICENSE.
- Added MANIFEST.in to exclude generated files in xhpy/tests/precompiled, as
  well as to pick up README.rst and LICENSE.
  • Loading branch information...
commit e9f1a664b40247a198a8e64b7d1b2ea3bc074178 1 parent 13dabd9
@candu authored
Showing with 82 additions and 34 deletions.
  1. +13 −0 LICENSE
  2. +5 −0 MANIFEST.in
  3. +35 −34 README.md → README.rst
  4. +29 −0 setup.py
View
13 LICENSE
@@ -0,0 +1,13 @@
+Copyright 2011 Evan Stratford
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
View
5 MANIFEST.in
@@ -0,0 +1,5 @@
+include LICENSE
+include README.rst
+# Exclusions should match XHPy-specific entries in .gitignore
+exclude xhpy/tests/precompiled/pylib
+exclude xhpy/tests/precompiled/*.py
View
69 README.md → README.rst
@@ -1,8 +1,9 @@
XHPy: XHP for Python
====================
-XHPy extends Python syntax such that XML document fragments become valid Python expressions.
-It is based off [XHP](https://github.com/facebook/xhp), a similar framework for PHP.
+`XHPy <https://github.com/candu/xhpy>`_ extends Python syntax such that XML document
+fragments become valid Python expressions. It is based off
+`XHP <https://github.com/facebook/xhp>`_, a similar framework for PHP.
Advantages
----------
@@ -17,12 +18,12 @@ Advantages
An example
----------
-In bar.py:
+In bar.py::
import xhpy.init
import foo
-In foo.py:
+In foo.py::
from xhpy.pylib import *
class :ui:foo(:x:element):
@@ -35,7 +36,7 @@ In foo.py:
return a
print <div class="baz"><ui:foo bar={range(3)} /></div>
-We can now run bar.py as a normal Python script:
+We can now run bar.py as a normal Python script::
$ python bar.py
<div class="baz"><ul><li>0</li><li>1</li><li>2</li></ul></div>
@@ -44,72 +45,72 @@ Congratulations! You just wrote your first snippet of XHPy.
Syntax
------
-XHPy adds some new syntax to Python. Line by line replay time!
+XHPy adds some new syntax to Python. Line by line replay time!::
import xhpy.init
This initializes XHPy; from now on, everything you import will be interpreted as XHPy.
-To actually use XHPy, however, you will probably want the core library:
+To actually use XHPy, however, you will probably want the core library::
from xhpy.pylib import *
-Now you have access to all the standard HTML 4.0 elements, the `:x:element` base class
-(this is what you build custom components on top of!), and some utilities.
+Now you have access to all the standard HTML 4.0 elements, the ``:x:element`` base class
+(this is what you build custom components on top of!), and some utilities.::
class :ui:foo(:x:element):
-Making new components is easy: just subclass `:x:element`. For your component class to be
-registered, it must start with `:` - this clearly distinguishes your components from
-ordinary Python classes.
+Making new components is easy: just subclass ``:x:element``. For your component class to be
+registered, it must start with ``:`` - this clearly distinguishes your components from
+ordinary Python classes.::
attribute list bar
-This is an attribute declaration, meaning that `:ui:foo` allows bar attributes on `<ui:foo>`
-tags. Note the
+This is an attribute declaration, meaning that ``:ui:foo`` allows bar attributes on ``<ui:foo>``
+tags. Note the::
<ui:foo bar={range(3)} />
-later on - like XHP, XHPy uses XML attribute syntax.
+later on - like XHP, XHPy uses XML attribute syntax.::
category %flow
-This is a category declaration - `:ui:foo` is part of the `%flow` category. Categories are
+This is a category declaration - ``:ui:foo`` is part of the ``%flow`` category. Categories are
primarily useful as a way of identifying elements that are similar without using
-inheritance; for example, the `<a>` tag in pylib.html has
+inheritance; for example, the ``<a>`` tag in pylib.html has::
children (pcdata | %flow)*
-indicating that its children must either contain text or be of the `%flow` category. (So
-we can put `<ui:foo>` inside `<a>`!)
+indicating that its children must either contain text or be of the ``%flow`` category. (So
+we can put ``<ui:foo>`` inside ``<a>``!)::
def render(self):
-When you print an `:x:element` (or call `__str__` on it), the `render()` method is invoked; this
-is where you put your UI logic.
+When you print an ``:x:element`` (or call ``str`` on it), the ``render()`` method is invoked; this
+is where you put your UI logic.::
a = <ul />
for b in self.getAttribute('bar'):
a.appendChild(<li>{b}</li>)
return a
-`<ui:foo>` is a thin wrapper around `<ul>` that allows you to construct an unordered
-list out of a Python list. Standard HTML elements like `<ul>` and `<li>` are automatically
-rendered - except that, in XHPy, you can use Python expressions within tags, so that
+Here, ``<ui:foo>`` is a thin wrapper around ``<ul>`` that allows you to construct an unordered
+list out of a Python list. Standard HTML elements like ``<ul>`` and ``<li>`` are automatically
+rendered - except that, in XHPy, you can use Python expressions within tags, so that::
{b}
-is replaced by the value of b. Note the use of `getAttribute()` and `appendChild()`:
+is replaced by the value of b. Note the use of ``getAttribute()`` and ``appendChild()``::
self.getAttribute('bar')
-fetches the value of attribute `bar` (in this case, `range(3)`), whereas
+fetches the value of attribute ``bar`` (in this case, ``range(3)``), whereas::
a.appendChild(<li>{b}</li>)
-adds `<li>{b}</li>` as a child of `a = <ul />`.
+adds ``<li>{b}</li>`` as a child of ``a = <ul />``.
XHPy is largely based off XHP; for more details on the latter, see the
-[XHP wiki](https://github.com/facebook/xhp/wiki/). The syntax has been adapted for
+`XHP wiki <https://github.com/facebook/xhp/wiki/`_. The syntax has been adapted for
Python; in particular:
- there are no semicolons;
@@ -117,7 +118,7 @@ Python; in particular:
- XHPy tags ignore internal whitespace, but must externally obey indentation and
line continuation rules.
-More on the last point:
+More on the last point::
def foo(href):
return <a href={href}></a>
@@ -126,29 +127,29 @@ More on the last point:
return\
<a href={href}></a>
-are valid, whereas
+are valid, whereas::
def foo(href):
return\
<a href={href}>
</a>
-is not, as it introduces an extra dedent after `</a>`.
+is not, as it introduces an extra dedent after ``</a>``.
How it works
------------
-When you
+When you::
import xhpy.init
-XHPy installs an [import hook](http://www.python.org/dev/peps/pep-0302/).
+XHPy installs an `import hook <http://www.python.org/dev/peps/pep-0302/>`_.
This hook traps all subsequent import statements, running them through a preprocessor
that parses a superset of Python. This preprocessor translates XHPy tags and class
names to valid Python, then executes the translated code in module scope.
This is similar to how XHP works, except:
-- with, e.g., [pythonenv](http://pypi.python.org/pypi/virtualenv), you can always use
+- with, e.g., `pythonenv <http://pypi.python.org/pypi/virtualenv>`_, you can always use
XHPy even without access to system-wide Python package installation directories;
- by default, Python compiles bytecode .pyc files from your modules, so the
preprocessing only needs to be done once when a module is first imported.
View
29 setup.py
@@ -0,0 +1,29 @@
+import os.path
+from distutils.core import setup
+
+ROOT = os.path.abspath(os.path.dirname(__file__))
+
+setup(
+ name = 'xhpy',
+ packages = ['xhpy'],
+ version = '0.6',
+ author = 'Evan Stratford',
+ author_email = 'evan.stratford@gmail.com',
+ license = 'Apache',
+ description = 'XHP for Python',
+ url = 'http://github.com/candu/xhpy',
+ keywords = ['xhp', 'html', 'xml'],
+ classifiers = [
+ 'Programming Language :: Python',
+ # TODO: test for Python 3 compatibility
+ 'License :: OSI Approved :: Apache Software License',
+ 'Operating System :: OS Independent',
+ 'Development Status :: 3 - Alpha',
+ 'Environment :: Web Environment',
+ 'Intended Audience :: Developers',
+ 'Topic :: Software Development :: Code Generators',
+ 'Topic :: Software Development :: Libraries :: Python Modules',
+ 'Topic :: Text Processing :: Markup'
+ ],
+ long_description = open(os.path.join(ROOT, 'README.rst')).read(),
+)
Please sign in to comment.
Something went wrong with that request. Please try again.