Re: Updated documentation on apache.import_module()
2006/12/4, Graham Dumpleton [EMAIL PROTECTED]:
Clodoaldo wrote ..
2006/12/3, Graham Dumpleton [EMAIL PROTECTED]:
Can you and anyone else who is interested, read through the
documentation
I have added and comment on whether it is adequate. Ie., is there
anything
that you can think is missing based on your own knowledge of the new
importer,
or anything that is particularly clear.
This paragraph is not clear for me:
In this scheme for maintaining a pseudo package, individual modules
are still placed into a directory, but there cannot be a __init__.py
file in the directory. If such a file does exist, it will simply be
ignored.
It says there cannot be a __init__.py file in the directory and
immediately after it says that if it exists it will be ignored. What
will be ignored? The file or the pseudo package?
Thinking about it the only way that the paragraph makes sense is if
the package is ignored but for me it is confusing at first sight.
Does this make more sense?
Although true Python packages are not candidates for reloading and must
be located in a directory listed in \code{sys.path}, another form of
packaging up modules such that they can be maintained within their own
namespace is supported. When this mechanism is used, these modules will
be candidates for reloading when found by the mod_python module importer.
In this scheme for maintaining a pseudo package, individual modules are
still placed into a directory, but the \code{__init__.py} file in the
directory has no special meaning and will not be automatically imported
as is the case with true Python packages. Instead, any module within the
directory must always be explicitly identified when performing an import.
To import a named module contained within these pseudo package, rather
than using a '.' to distinguish a sub module from the parent, a '/' is
used instead. For example:
\begin{verbatim}
from mod_python import apache
module = apache.import_module('dirname/module_name')
\end{verbatim}
If an \code{__init__.py} file is present and it was necessary to import
it to achieve the same result as importing the root of a true Python
package, then \code{__init__} can be used as the module name. For example:
\begin{verbatim}
from mod_python import apache
module = apache.import_module('dirname/__init__')
\end{verbatim}
As a true Python package is not being used, if a module in the directory
needs to refer to another module in the same directory, it should use
just its name, it should not use any form of dotted path name via the
root of the package as with true Python packages. Modules in
subdirectories can be imported by using a '/' separated path where the
first part of the path is the name of the subdirectory.
Graham
It is clear now for me.
--
Clodoaldo Pinto Neto
Re: Updated documentation on apache.import_module()
Clodoaldo wrote:
2006/12/3, Graham Dumpleton [EMAIL PROTECTED]:
Jim, I have updated LaTeX documentation for the apache.import_module()
function. Can you run it through LaTeX and fixup all my wrongly
closed LaTeX
formatting. :-)
Can you and anyone else who is interested, read through the
documentation
I have added and comment on whether it is adequate. Ie., is there
anything
that you can think is missing based on your own knowledge of the new
importer,
or anything that is particularly clear.
Typos:
psuedo:
In this scheme for maintaining a psuedo package,
psuedo:
converted into the psuedo packages that mod_python supports
out out and missing \ before code:
the function directory out out the code{mod_python.apache} module
Thanks. I made the changes and uploaded the new page to the
people.apache.org/~jgallacher for further review.
Jim
Re: Updated documentation on apache.import_module()
Graham Dumpleton wrote:
Jim, I have updated LaTeX documentation for the apache.import_module()
function. Can you run it through LaTeX and fixup all my wrongly closed
LaTeX
formatting. :-)
Can you and anyone else who is interested, read through the documentation
I have added and comment on whether it is adequate. Ie., is there anything
that you can think is missing based on your own knowledge of the new
importer,
or anything that is particularly clear.
I realise that this documentation should perhaps have been in a whole
section
by itself, but just wanted to get something in there so we can get this
thing out
the door and released before I get too eager and start sneaking in even
more
code changes. :-)
For those who don't check out code from subversion, the documentation can
be seen at:
http://svn.apache.org/viewvc/httpd/mod_python/trunk/Doc/modpython4.tex?view=markup
Search down for 'import_module'.
I'll check it all again in a day or so when I have a clear head.
Graham
Quoting from import_module section of pyapi-apmeth.html#l2h-32:
With the reimplementation of the module importer in mod_python 3.3, the
module_name argument may also now be an absolute path name of an actual
Python module contained in a single file. On Windows, a drive letter can
be supplied if necessary.
from mod_python import apache
name = apache.import_module('/some/path/name.py')
The actual code tests for the presence for [~/, ./, ../] so maybe
it needs to be explicitly stated that Unix style path separators are
required on Windows? I don't do python on Windows, so maybe that is
standard practice, but explicit is better than implicit.
Jim
Re: Updated documentation on apache.import_module()
Graham Dumpleton wrote:
Jim, I have updated LaTeX documentation for the apache.import_module()
function. Can you run it through LaTeX and fixup all my wrongly closed
LaTeX
formatting. :-)
It would seem LaTeX doesn't like naked tilde characters, as ~ is used
for markup. Something like:
The '~/' prefix should be used.
becomes
The 'nbsp;/' prefix should be used.
in the generated html.
I thought \character{\~} might work, but that surrounds the tilde with
quotes so
The '\character{\~}/' prefix should be used.
becomes
The '~/' prefix should be used.
If anyone knows a fix please let me know. In the mean time I'll dig into
LaTeX and try to figure it out.
Jim
Re: Updated documentation on apache.import_module()
Jim Gallacher wrote:
Graham Dumpleton wrote:
Jim, I have updated LaTeX documentation for the apache.import_module()
function. Can you run it through LaTeX and fixup all my wrongly closed
LaTeX
formatting. :-)
It would seem LaTeX doesn't like naked tilde characters, as ~ is used
for markup. Something like:
The '~/' prefix should be used.
becomes
The 'nbsp;/' prefix should be used.
in the generated html.
The solution is to use \textasciitilde, so
The '\textasciitilde/' prefix should be used.
becomes
The '~/' prefix should be used.
Note that the ~ character can be used without substitution within
\begin{verbatim} and \end{verbatim}.
I'll fix and commit the changes to the docs.
Jim
Re: Updated documentation on apache.import_module()
2006/12/3, Jim Gallacher [EMAIL PROTECTED]: Can you and anyone else who is interested, read through the documentation I have added and comment on whether it is adequate. Ie., is there anything that you can think is missing based on your own knowledge of the new importer, or anything that is particularly clear. I built the html docs and uploaded them to a temporary location, which people may find easier to read than the LateX. http://people.apache.org/~jgallacher/mod_python/dist/mod_python-3.3.0-dev-20061203/doc-html/ I believe the relevant bits are: http://people.apache.org/~jgallacher/mod_python/dist/mod_python-3.3.0-dev-20061203/doc-html/pyapi-apmeth.html#l2h-32 http://people.apache.org/~jgallacher/mod_python/dist/mod_python-3.3.0-dev-20061203/doc-html/dir-other-pimp.html Missing reference here: http://people.apache.org/~jgallacher/mod_python/dist/mod_python-3.3.0-dev-20061203/doc-html/dir-other-pimp.html Reference should be made to the documentation of that function for further details of how module importing is managed. -- Clodoaldo Pinto Neto
Re: Updated documentation on apache.import_module()
Jim Gallacher wrote:
Jim Gallacher wrote:
Graham Dumpleton wrote:
Jim, I have updated LaTeX documentation for the apache.import_module()
function. Can you run it through LaTeX and fixup all my wrongly
closed LaTeX
formatting. :-)
It would seem LaTeX doesn't like naked tilde characters, as ~ is used
for markup. Something like:
The '~/' prefix should be used.
becomes
The 'nbsp;/' prefix should be used.
in the generated html.
The solution is to use \textasciitilde, so
The '\textasciitilde/' prefix should be used.
becomes
The '~/' prefix should be used.
Note that the ~ character can be used without substitution within
\begin{verbatim} and \end{verbatim}.
I'll fix and commit the changes to the docs.
Using a tilde in a url is also messed up, and the \textasciitilde
macro does not help. The solution is to use the hex
encoding (%7e) for the tilde, so:
\seeurl{http://people.apache.org/~jgallacher}
should be written as:
\seeurl{http://people.apache.org/%7ejgallacher}
Jim
Re: Updated documentation on apache.import_module()
2006/12/3, Graham Dumpleton [EMAIL PROTECTED]: Can you and anyone else who is interested, read through the documentation I have added and comment on whether it is adequate. Ie., is there anything that you can think is missing based on your own knowledge of the new importer, or anything that is particularly clear. This paragraph is not clear for me: In this scheme for maintaining a pseudo package, individual modules are still placed into a directory, but there cannot be a __init__.py file in the directory. If such a file does exist, it will simply be ignored. It says there cannot be a __init__.py file in the directory and immediately after it says that if it exists it will be ignored. What will be ignored? The file or the pseudo package? Thinking about it the only way that the paragraph makes sense is if the package is ignored but for me it is confusing at first sight. -- Clodoaldo Pinto Neto
Re: Updated documentation on apache.import_module()
Clodoaldo wrote: 2006/12/3, Graham Dumpleton [EMAIL PROTECTED]: Can you and anyone else who is interested, read through the documentation I have added and comment on whether it is adequate. Ie., is there anything that you can think is missing based on your own knowledge of the new importer, or anything that is particularly clear. This paragraph is not clear for me: In this scheme for maintaining a pseudo package, individual modules are still placed into a directory, but there cannot be a __init__.py file in the directory. If such a file does exist, it will simply be ignored. It says there cannot be a __init__.py file in the directory and immediately after it says that if it exists it will be ignored. What will be ignored? The file or the pseudo package? Thinking about it the only way that the paragraph makes sense is if the package is ignored but for me it is confusing at first sight. I believe he's saying the following: Normally putting an __init__.py, even an empty one, will cause the directory to act as a package and you can therefore of import directory name or from directory name import something. However using the mod_python path invalidates that package behavior, so if you have a package that relies on code in __init__.py to be executed on import, it won't work any more. Please correct me if I'm wrong, but I think that's the behavior I'm seeing.
Re: Updated documentation on apache.import_module()
Clodoaldo wrote ..
2006/12/3, Graham Dumpleton [EMAIL PROTECTED]:
Can you and anyone else who is interested, read through the
documentation
I have added and comment on whether it is adequate. Ie., is there
anything
that you can think is missing based on your own knowledge of the new
importer,
or anything that is particularly clear.
This paragraph is not clear for me:
In this scheme for maintaining a pseudo package, individual modules
are still placed into a directory, but there cannot be a __init__.py
file in the directory. If such a file does exist, it will simply be
ignored.
It says there cannot be a __init__.py file in the directory and
immediately after it says that if it exists it will be ignored. What
will be ignored? The file or the pseudo package?
Thinking about it the only way that the paragraph makes sense is if
the package is ignored but for me it is confusing at first sight.
Does this make more sense?
Although true Python packages are not candidates for reloading and must
be located in a directory listed in \code{sys.path}, another form of
packaging up modules such that they can be maintained within their own
namespace is supported. When this mechanism is used, these modules will
be candidates for reloading when found by the mod_python module importer.
In this scheme for maintaining a pseudo package, individual modules are
still placed into a directory, but the \code{__init__.py} file in the
directory has no special meaning and will not be automatically imported
as is the case with true Python packages. Instead, any module within the
directory must always be explicitly identified when performing an import.
To import a named module contained within these pseudo package, rather
than using a '.' to distinguish a sub module from the parent, a '/' is
used instead. For example:
\begin{verbatim}
from mod_python import apache
module = apache.import_module('dirname/module_name')
\end{verbatim}
If an \code{__init__.py} file is present and it was necessary to import
it to achieve the same result as importing the root of a true Python
package, then \code{__init__} can be used as the module name. For example:
\begin{verbatim}
from mod_python import apache
module = apache.import_module('dirname/__init__')
\end{verbatim}
As a true Python package is not being used, if a module in the directory
needs to refer to another module in the same directory, it should use
just its name, it should not use any form of dotted path name via the
root of the package as with true Python packages. Modules in
subdirectories can be imported by using a '/' separated path where the
first part of the path is the name of the subdirectory.
Graham
