Sometimes it is neccessary to persist more complicated objects than strings.
-With some care, dirdbm.Shelf
-can transparently persist
-them. Shelf works exactly like DirDBM, except that
-the values (but not the keys) can be arbitrary picklable objects. However,
-notice that mutating an object after it has been stored in the
-Shelf has no effect on the Shelf.
-When mutating objects, it is neccessary to explictly store them back in the Shelf
-afterwards:
Sometimes it is neccessary to persist more complicated objects than
+strings. With some care, dirdbm.Shelf can transparently persist
+them. Shelf works exactly like DirDBM,
+except that the values (but not the keys) can be arbitrary picklable
+objects. However, notice that mutating an object after it has been
+stored in the Shelf has no effect on the Shelf. When
+mutating objects, it is neccessary to explictly store them back in
+the Shelf afterwards:
>>> from twisted.persisted import dirdbm diff --git a/doc/core/howto/telnet.xhtml b/doc/core/howto/telnet.xhtml index 933dd84..f7e687e 100644 --- a/doc/core/howto/telnet.xhtml +++ b/doc/core/howto/telnet.xhtml @@ -16,15 +16,15 @@ be on port 4040, and it will start listening for connections on this port. Try connecting with your favorite telnet utility to 127.0.0.1 port 4040.-$ telnet localhost 4040 +$ telnet localhost 4040 Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. twisted.manhole.telnet.ShellFactory Twisted 1.1.0 -username: admin -password: admin +username: admin +password: admin >>>@@ -33,36 +33,37 @@ password: admin here. Let's try looking around.->>> dir() +>>> dir() ['__builtins__']Ok, not much. let's play a little more:
->>> import __main__ ->>> dir(__main__) +>>> import __main__ +>>> dir(__main__) ['__builtins__', '__doc__', '__name__', 'os', 'run', 'string', 'sys'] ->>> service +>>> service <twisted.application.internet.TCPServer instance at 0x10270f48> ->>> service._port +>>> service._port <twisted.manhole.telnet.ShellFactory on 4040> ->>> service.parent +>>> service.parent <twisted.application.service.MultiService instance at 0x1024d7a8>The service object is the service used to serve the telnet shell, -and that it is listening on port 4040 with something called a -
+and that it is listening on port 4040 with something called +aShellFactory. -Its parent is atwisted.application.service.MultiService, -a collection of services. We can keep getting the parent attribute -of services until we hit the root of all services.ShellFactory. +Its parent is +atwisted.application.service.MultiService, +a collection of services. We can keep getting the parent attribute of +services until we hit the root of all services. -As you can see, this is quite useful - we can introspect a -running process, see the internal objects, and even change -their attributes. The telnet server can of course be used from straight -Python code; you can see how to do this by reading the code for -
+twisted.tap.telnet.As you can see, this is quite useful - we can introspect a running +process, see the internal objects, and even change their +attributes. The telnet server can of course be used from straight +Python code; you can see how to do this by reading the code +for
twisted.tap.telnet.A final note - if you want access to be more secure, you can even have the telnet server use SSL. Assuming you have the appropriate diff --git a/doc/core/howto/testing.xhtml b/doc/core/howto/testing.xhtml index e83e8d2..0b60709 100644 --- a/doc/core/howto/testing.xhtml +++ b/doc/core/howto/testing.xhtml @@ -68,24 +68,26 @@ may complete (and fail) during a later test. These lead to intermittent failures that wander from test to test and are very time-consuming to track down.
-If your test leaves event sources in the reactor, Trial will fail the test. -The
- -tearDownmethod is a good place to put cleanup code: it is -always run regardless of whether your test passes or fails (like a bare-exceptclause in a try-except construct). Exceptions intearDown -are flagged as errors and flunk the test. -TestCase.addCleanupis -another useful tool for cleaning up. With it, you can register callables to -clean up resources as the test allocates them. Generally, code should be -written so that only resources allocated in the tests need to be cleaned up in -the tests. Resources which are allocated internally by the implementation -should be cleaned up by the implementation.If your code uses Deferreds or depends on the reactor running, you can -return a Deferred from your test method, setUp, or tearDown and Trial will -do the right thing. That is, it will run the reactor for you until the -Deferred has triggered and its callbacks have been run. Don't use -
+reactor.run(),reactor.stop(),reactor.crash() -orreactor.iterate()in your tests.If your test leaves event sources in the reactor, Trial will fail +the test. The
+ +tearDownmethod is a good place to put +cleanup code: it is always run regardless of whether your test passes +or fails (like a bareexceptclause in a try-except +construct). Exceptions intearDownare flagged as errors +and flunk the test.TestCase.addCleanupis another +useful tool for cleaning up. With it, you can register callables to +clean up resources as the test allocates them. Generally, code should +be written so that only resources allocated in the tests need to be +cleaned up in the tests. Resources which are allocated internally by +the implementation should be cleaned up by the implementation.If your code uses Deferreds or depends on the reactor running, you +can return a Deferred from your test method, setUp, or tearDown and +Trial will do the right thing. That is, it will run the reactor for +you until the Deferred has triggered and its callbacks have been +run. Don't +use
reactor.run(),reactor.stop(),reactor.crash()orreactor.iterate()+in your tests.Calls to
reactor.callLatercreateIDelayedCalls. These need to be run @@ -132,21 +134,24 @@ in unusual cases.Interacting with warnings in tests
-Trial includes specific support for interacting with Python's -
+warningsmodule. This support allows warning-emitting code to -be written test-driven, just as any other code would be. It also improves -the way in which warnings reporting when a test suite is running.Trial includes specific support for interacting with +Python's
warningsmodule. This support allows +warning-emitting code to be written test-driven, just as any other +code would be. It also improves the way in which warnings reporting +when a test suite is running.+base="twisted.trial.unittest">TestCase.assertWarns +and
TestCase.assertWarnsandTestCase.flushWarnings-allow tests to be written which make assertions about what warnings have -been emitted during a particular test method.flushWarningsis -the new method and has a simpler and more flexible API and should be -preferred when writing new code. In order to test a warning with -flushWarnings, write a test which first invokes the code which -will emit a warning and then callsflushWarningsand makes -assertions about the result. For example:TestCase.flushWarningsallow +tests to be written which make assertions about what warnings have +been emitted during a particular test +method.flushWarningsis the new method and has a +simpler and more flexible API and should be preferred when writing new +code. In order to test a warning withflushWarnings, +write a test which first invokes the code which will emit a warning +and then callsflushWarningsand makes assertions about +the result. For example:def test_warning(self): @@ -154,18 +159,19 @@ def test_warning(self): self.assertEqual(len(self.flushWarnings()), 1)-Warnings emitted in tests which are not flushed will be included by the -default reporter in its output after the result of the test. If Python's -warnings filter system (see the -W command -line option to Python) is configured to treat a warning as an error, -then unflushed warnings will causes tests to fail and will be included in -the summary section of the default reporter. Note that unlike usual -operation, when
+warnings.warnis called as part of a test -method, it will not raise an exception when warnings have been configured as -errors. However, if called outside of a test method (for example, at module -scope in a test module or a module imported by a test module) then it -will raise an exception.Warnings emitted in tests which are not flushed will be included by +the default reporter in its output after the result of the test. If +Python's warnings filter system +(see the +-W command line option to Python) is configured to treat a warning +as an error, then unflushed warnings will causes tests to fail and +will be included in the summary section of the default reporter. Note +that unlike usual operation, when
warnings.warnis called +as part of a test method, it will not raise an exception when warnings +have been configured as errors. However, if called outside of a test +method (for example, at module scope in a test module or a module +imported by a test module) then it will raise an +exception.