Revision: 2220
Author: pekka.klarck
Date: Sat Aug 15 14:00:36 2009
Log: quite a lot changes, work still in progress
http://code.google.com/p/robotframework/source/detail?r=2220
Modified:
/trunk/doc/python/PythonTutorial.rst
=======================================
--- /trunk/doc/python/PythonTutorial.rst Sat Aug 15 08:21:46 2009
+++ /trunk/doc/python/PythonTutorial.rst Sat Aug 15 14:00:36 2009
@@ -531,30 +531,31 @@
Modules
-------
-Importing Modules
+Importing modules
'''''''''''''''''
-* Importing existing Python modules is as simply as saying ``import
- modulename``.
-
-* Alternative syntax is ``from modulename import submodule``.
-
-* Python has a comprehensive `standard library`_ so already there's
- plenty of existing code to be imported!
+* Importing existing Python modules is as simply as saying :code:`import
+ modulename`.
+
+* An alternative syntax is :code:`from modulename import something`.
+
+* Python has a comprehensive `standard library`_ so there is plenty of
+ existing code to be imported. It is recommended to study what is
+ available to avoid reinventing wheels.
-Creating Modules
+Creating modules
''''''''''''''''
-* Every ``.py`` file is effectively a Python module so you have
- already created some modules.
-
-* For example we could have following code in a file called ``test.py``:
+* Every :path:`.py` file is effectively a Python module, so you have
+ already created at least :code:`hello` module.
+
+* For example we could have following code in a file
called :path:`example.py`:
.. sourcecode:: python
def hello(name="World"):
- print "Hello, %s" % name
+ print "Hello, %s!" % name
if __name__ == "__main__":
hello()
@@ -563,21 +564,20 @@
.. sourcecode:: pycon
- >>> import test
- >>> test.hello("Tellus")
- Hello, Tellus
-
-* ``if __name__ == "__main__"`` block in the previous example is
- important because it allows executing the file as a script (``python
- test.py``) and using it as a module like above. Automatic
- ``__name__`` attribute (Python has many of these as you'll see if
- you study it more) gets value ``"__main___"`` when the file is run
- as a script and the ``if`` block is thus executed only in that case.
-
-* Bigger modules can be organized into several files and a higher
- level module (also called package) created to contain them as
- submodules. In this case the higher level module is a directory with
- a special ``___init___.py`` file.
+ >>> import example
+ >>> example.hello("Tellus")
+ Hello, Tellus!
+
+* :code:`if __name__ == "__main__"` block in the previous example is
+ important because it allows executing the file also as a script like
+ :cli:`python example.py`. Automatic :code:`__name__` attribute
+ (Python has many of these as you will see if you study it more) gets
+ value :code:`"__main___"` when the file is run as a script and the
+ if block is thus executed only in that case.
+
+* Bigger modules can be organized into several files inside a higher
+ level module as submodules. In this case the higher level module is
+ a directory with a special :path:`___init___.py` file.
* For more information about modules see
http://docs.python.org/tut/node8.html
@@ -587,29 +587,30 @@
Module search path (PYTHONPATH)
'''''''''''''''''''''''''''''''
-* Python modules aren't automatically searched everywhere on you
+* Python modules are not automatically searched everywhere on you
machine. Python has certain default places to search modules for
- (e.g. it's own library directory which is often in place like
- ``C:\Python26\Lib`` or ``/usr/lib/python2.6``) and additionally it
- looks for them from so called PYTHONPATH.
-
-* PYTHONPATH is an environment variable which contains places (mainly
- directories) to look for Python modules. It is similar to
- PATH environment variable which is used by an operating system to
- look for executable programs.
-
-* PYTHONPATH is important also with Robot because it can import test
- libraries only if the module containing the library can be imported.
+ (e.g. its own library directory which is often in place like
+ :path:`C:\Python26\Lib` or :path:`/usr/lib/python2.6`) and
+ additionally it looks for them from so called :var:`PYTHONPATH`.
+
+* :var:`PYTHONPATH` is most often controlled using an environment
+ variable with the same name that contains places (mainly
+ directories) to look for Python modules. It is similar to Java's
+ :var:`CLASSPATH` and also to :var:`PATH` environment variable which
+ is used by an operating system to look for executable programs.
+
+* :var:`PYTHONPATH` is important also with Robot Framework because it
+ can import test libraries only if the module containing the library
+ can be imported.
-Classes and Instances
+Classes and instances
---------------------
-* Python is an object-oriented language but as we've seen you don't
- need to use classes everywhere like you need to in Java for
- example. It's totally ok to just have a module with functions if
- that's suites your needs but often object oriented features are
- really handy.
+* Python is an object-oriented language but as we have seen you do not
+ need to use classes everywhere like you need to with Java. It is
+ totally fine to just have a module with functions if that suites
+ your needs but object oriented features are often really handy.
* The syntax for creating classes and then instances from them is
relatively straightforward:
@@ -628,11 +629,11 @@
>>> c.hello('Tellus')
Robot says hello to Tellus.
-* The really weird thing in the syntax is that every class method must
- have ``self`` as the first argument in the signature. After you
- create an instance of the class Python *binds* the method and takes
- care of passing the ``self`` argument automatically so you don't use
- it when calling the method.
+* The only surprising part in the syntax is that every class method
+ must have :code:`self` as the first argument in the signature. After
+ you create an instance of the class Python binds the method and
+ takes care of passing the :code:`self` argument automatically so you
+ do not use it when calling the method.
* To learn more about classes you can follow `a pretty interesting
example from Dive Into Python
@@ -645,20 +646,22 @@
----------
* Python has an exception system similar to many other languages.
- Exceptions are classes and the normal way to raise them is ``raise
- SomeException("Error message")``. Exceptions are handled in a
- ``try/except`` block.
-
-* Compared to Java there are some terminology differences (``raise``
- vs. ``throw`` and ``except`` vs.``catch``) but the biggest real
- difference to is that there are no checked exceptions i.e. you don't
- need to add ``throws SomeException`` to those methods that possibly
- raise exceptions.
+ Exceptions are classes and the normal way to raise them is
+ :code:`raise SomeException("Error message")`.
+
+* Exceptions are handled in a :code:`try/except` block which can have
+ an optional :code:`finally` branch.
+
+* Compared to Java there are some terminology differences
+ (:code:`raise` vs. :code:`throw` and :code:`except`
+ vs. :code:`catch`) but the biggest real difference to is that there
+ are no checked exceptions. This means that you do not need to add
+ :code:`throws SomeException` to methods that may raise an exception.
* More info: http://diveintopython.org/file_handling/index.html
-* Exceptions are an important part of the Robot Library API because
- keywords use them to communicate failures to the framework.
+* Exceptions are an important part of the Robot Framework Library API
+ because keywords use them to communicate failures to the framework.
Regular Expressions
@@ -668,8 +671,8 @@
a really common need in test automation.
* Python has a really fast regular expression engine and it uses a
- syntax that is derived from Perl's regexp syntax similarly as
- e.g. Java.
+ syntax derived from Perl's regexp syntax similarly as Java and many
+ other languages.
* A good introduction is
http://diveintopython.org/regular_expressions/index.html
@@ -683,10 +686,10 @@
idea.
* Python has several unit testing frameworks. Two of them,
- ``unittest`` and ``doctest``, are in the standard library. The
- former is immediately familiar for anyone who has used JUnit or
- some other xUnit framework and the other is interesting because it
- allows using function doc strings for tests.
+ :code:`unittest` and :code:`doctest`, are in the standard
+ library. The former is immediately familiar for anyone who has used
+ JUnit or some other xUnit framework and the other is interesting
+ because it allows using function doc strings for tests.
* Dive Into Python has really good chapters about
@@ -702,14 +705,19 @@
Writing Test Libraries
----------------------
-Robot Framework's test library API is really simple. The test library can
be
-either a module or a class. In case of a module, a keyword will be
created for
-each top-level function in the module. In case of a class, a keyword will
be
-created for each public method of the class.
-
-Keyword may return values using the `return` statement. A failure is
generated
-by raising an exception. `print` statement can be used to log a message
from a
-keyword. The example library below illustrates these features:
+Robot Framework's test library API is really simple. It is explained
+fully in the `User Guide`_ but the basic features are covered here
+with an example.
+
+The test library can be either a module or a class. In case of a
+module, a keyword will be created for each top-level function in the
+module. In case of a class, a keyword will be created for each public
+method of the class.
+
+Keyword may return values using the :code:`return` statement, a
+failure is generated by raising an exception, and :code:`print`
+statement can be used to log a message from a keyword. The example
+library below illustrates these features:
.. sourcecode:: python
@@ -725,5 +733,6 @@
.. footer:: Generated by reStructuredText_. Syntax highlighting by
Pygments_.
+.. _user guide: http://code.google.com/p/robotframework/wiki/UserGuide
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Pygments: http://pygments.org/
