Commits

Rudy Lattae committed 070e749

Deprecating the project in favor of 'compare' and 'checkit'.

Comments (0)

Files changed (5)

-Copyright (c) 2010, Rudy Lattae
-All rights reserved.
+    Copyright (c) 2010, Rudy Lattae.
 
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-    * Redistributions of source code must retain the above copyright
-      notice, this list of conditions and the following disclaimer.
-    * Redistributions in binary form must reproduce the above copyright
-      notice, this list of conditions and the following disclaimer in the
-      documentation and/or other materials provided with the distribution.
-    * Neither the name of Rudy Lattae nor the
-      names of its contributors may be used to endorse or promote products
-      derived from this software without specific prior written permission.
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+    
+        * Redistributions of source code must retain the above copyright
+          notice, this list of conditions and the following disclaimer.
+        * Redistributions in binary form must reproduce the above copyright
+          notice, this list of conditions and the following disclaimer in the
+          documentation and/or other materials provided with the distribution.
+        * Neither the name of Rudy Lattae nor the
+          names of its contributors may be used to endorse or promote products
+          derived from this software without specific prior written permission.
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL Rudy Lattae BE LIABLE FOR ANY
-DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+    DISCLAIMED. IN NO EVENT SHALL Rudy Lattae BE LIABLE FOR ANY
+    DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-======
-specit
-======
+Overview
+========
 
-specit assists in creating and running executable specifications.
-The commandline runner uses nose to discover and execute 
-specifications using flexible matching rules so that you do 
-not need to use distracting unittest constructs like "def test..." 
-or "self.assertTrue...".
+**NOTE**
 
-It also provides an "expect" construct with extensible matchers 
-that enable you to describe the behaviour of your software using simple, 
-pythonic BDD style grammar. Here is a simple example to illustrate 
-how you may create specs using expect::
+Specit is no longer actively developed. It has been replaced by:
+- compare: for the pluggable `expect` syntax
+-- package: http://pypi.python.org/pypi/compare/
+-- source: https://github.com/rudylattae/compare/
+-- docs: http://packages.python.org/compare/
+- checkit: enables `nose` to detect and run test cases defined using BDD style "describe" and "it"
+-- package: http://pypi.python.org/pypi/checkit/
+-- source: https://bitbucket.org/rudylattae/checkit/
 
-    >>> from specit import expect
-    >>> import specit
-    
-    >>> def greet():
-    ...     return 'Hello you'
-    
-    >>> expect(greet).to_return('Hello you')
+-----
 
 
-Goals
-=====
+Specit is a minimalistic tool to assist developers in creating 
+and validating executable specifications for python software. It 
+aims to:
 
-1. Provide a readable, pythonic syntax for defining expectations 
-in executable specifications.
+1. Provide a readable, pythonic syntax for defining expectations in your example specifications.
+2. Provide a simple tool for validating your specifications. 
 
-2. Provide a simple tool for discovering and running executable 
-specifications in Python. 
-
-
-Motivation
-==========
-
-In Python land, the defacto unit testing product is the builtin unittest 
-module. I always have difficulty creating "unit specs" using unittest 
-because the grammar and style it promotes are in my opinion, counter-intuitive 
-and not pythonic. I needed an alternative component-level specification 
-tool that would allow me to create and run specs in a manner that encourages 
-me to focus on designing or discovering the behaviour of my software NOT on 
-testing it. 
-
-So I `google'd <http://www.google.com/search?q=python+bdd+tools>`_ and 
-`pypi'ed <http://pypi.python.org/pypi?:action=search&term=bdd&submit=search>`_ 
-and even read a 
-`discussion <http://stackoverflow.com/questions/231371/practicing-bdd-with-python>`_ 
-or two.
-
-I found a few intriguing options which I decided against because of the 
-reasons below:
- 
-* `SpecLoud <https://github.com/hugobr/specloud>`_: it looks good but it only provides a runner and the installation is not as simple as I would like.
-* `Should-DSL <http://www.should-dsl.info>`_: even though I was draw to Should-DSL earlier on, I just could not get over the fact that I need to wrap the "should"/"should_not" constructs with pipes "||". It seems un-pythonic.
-* `Describe <https://github.com/jeffh/describe>`_: I like the ".should" matcher syntax. However, it seems there is a lot going on under the hood -- I need something brain-dead simple.
-
-I strongly urge you to take a look at the above projects. They are all good 
-projects in many way and one of them could be exactly what you are looking for. 
-As with anything in life, YMMV.
-
-After eliminating the potentials above, I decided to create specit because 
-I wanted a compact "batteries included" tool which would help me create and 
-run pythonic specifications. 
-
-Since `nose <http://somethingaboutorange.com/mrl/projects/nose>`_
-is already a great test discoverer/runner with a healty eco-system of plugins, 
-I figured it would be best for specit to leverge it's abilities. i.e. Life's 
-short, so don't re-invent the wheel unless you absolutely must.
+To this end, specit provides two components to simplify your 
+work with specs. The **expect** construct allows you to indicate 
+verifyable expectations of your software. It is a replacement for
+the "self.assert..." syntax. The **specit** command uses 
+`Nose <http://somethingaboutorange.com/mrl/projects/nose>`_ to 
+validate your specifications.
 
 
 Features
-========
+--------
 
 - uses nose for discovering and running specs
 - provides a base set of matchers for defining expectations
 - easy to extend with custom matchers
 
 
+Requirements
+------------
+
+All the requirements for using specit are auto-installed if you 
+use pip or easy_install. Here they are:
+
+- `Nose <http://somethingaboutorange.com/mrl/projects/nose>`_ 
+
+
 Installation
-============
+------------
 
-With pip
+The easiest way to install specit is with ``pip install spectit`` 
+or with ``easy_install specit``. Alternatively, you may 
+`download <http://pypi.python.org/pypi/specit>`_ the 
+source package from PyPI, extract it and install it using 
+``python setup.py install``.
+
+
+What you get
+------------
+
+When you install the package, you get two shiny components that 
+may help you achieve the goals above.
+
+**"expect"**, is the grammar component. It provides a construct with 
+extensible matchers that enables you to describe the expected 
+behaviour of your software using a pythonic BDD manner. Again, this 
+helps you maintain your flow of thought without succumbing to 
+test-focused non-pythonic distrations like "self.assertEqual(s)...", 
+"self.assertTrue", etc.
+
+**"specit"**, is the commandline component. It uses nose to discover 
+and execute specifications using flexible matching rules so that you 
+are not limited to using distracting unittest (test focused) constructs 
+like "def test..." or name your files "test...py".
+
+Here is a trivial example of the clarity you gain when you 
+employ the "expect" construct in your specs::
+
+    > cat greeting.py
+    def greet():
+        return 'Hello you'
+    
+    > cat greeting_specs.py
+    from specit import expect
+    from greeting import greet
+        
+    expect(greet).to_return('Hello you')
+
+Even more iteresting is the fact that you no longer have to 
+subject yourself to the unnecessary cruft needed for unittest 
+test cases. You can now create a spec like this::
+
+    > cat cool_specs.py
+    class DescribeCool(object):
+        
+        def it_is_cool(self):
+            pass
+
+Or even::
+
+    > cat awesome_specs.py
+    class MyAwesomeSpecs():
+    
+        def should_always_smile(self):
+            pass
+
+Finally, when you want to validate your software against the sepcs, 
+simply run the commandline tool "specit" in your project 
+directory like so::
+
+    > specit
+    ..
+    ----------------------------------------------------------------------
+    Ran 2 tests in 0.006s
+
+    OK
+
+
+Feedback
 --------
 
-If you have pip installed, you may install upgrade or uninstall 
-specit with these commands::
-
-    > pip install specit
-    > pip install -U specit
-    > pip uninstall specit
-    
-With easy_install
------------------
-
-If you do not have pip you may use easy install::
-
-    > easy_install specit
-
-    
-From source
------------
-
-If you do not have pip or easy_install, you may 
-`download <http://pypi.python.org/pypi/specit>`_ 
-the source distribution archive. Extract its contents, 
-go into the resulting "specit" directory and run::
-
-    > python setup.py install
-
-
-Example usage 
-=============
-
-Verifying expectations with the basic matchers
-----------------------------------------------
-
-Below is a simple example showing how you use the builtin matchers
-to craft readable specifications for your code::
-
-    >>> from specit import expect
-    
-    >>> fruit = 'Orange'
-    
-    >>> expect(fruit).to_equal('Orange')
-    >>> expect(fruit).to_equal('Apple')
-    Traceback (most recent call last):
-        ...
-    AssertionError: Expected 'Orange' to equal 'Apple'
-    
-
-Creating and using custom matchers
-----------------------------------
-
-A specit matcher is a regular python function that can be 
-wired into the Expect class. You may extend specit with 
-custom matchers that make make your examples succinct and 
-easy to follow::
-
-    >>> from specit import expect, matcher, ensure
-    
-    >>> @matcher
-    ... def to_be_citrus(self):
-    ...     ensure(self.actual in ['Orange'], True, "Expected %s to be a citrus fruit" % self.actual)
-    
-    >>> fruit = 'Orange'
-    >>> expect(fruit).to_be_citrus()
-
-
-Running your specs from the command line
-----------------------------------------
-
-When you install specit, you get a command line tool "specit" 
-installed into your Python scripts directory. Assuming the your 
-scripts dir is on yout PATH, you will be able to execute your 
-specifications simply by calling specit inside your project. 
-
-Below is a trivial example project layout for a simple module::
-
-    project/
-        |-- mycoolthing.py
-        |-- specs.py
-
-From the root directory of your project, you may run the 
-specifications in specs.py like so::
-
-    > specit
-    
-    
-If you wish to see a detailed output, just run specit with the '-v' 
-parameter::
-
-    > specit -v
-
-There are many more options you may pass to the "specit" command. 
-Please see the "How it works" section for more information.
-
-
-How it works
-============
-
-The specit commandline tool "specit" is simply a wrapper for nose, 
-specifically, the "nosetests" command that is installed with nose. 
-The specit command basically calls the nosetests command with some arguments 
-that tell it to look for tests in files with names like "spec(s)", "example(s)", 
-etc. It also tells nosetests to treat methods or classes with names like 
-"Describe...", "...Specs", "it...", etc. as test cases, or in BDD terms 
-specification examples.
-
-Nose itself provides a lot of useful features out of the box. Please 
-refer to the `Nose site <http://somethingaboutorange.com/mrl/projects/nose>`_ 
-for further information.
-
-If you are interested in knowing more about the options you can pass to 
-the specit (nosetests wrapper) command, you should look at the 
-`nose usage documentation <http://somethingaboutorange.com/mrl/projects/nose/1.0.0/usage.html#options>`_.
-
-
-Contribute
-==========
-
 I welcome any questions or feedback about bugs and suggestions on how to 
-improve specit.
-
-As a user
----------
-
-Let me know what you think about specit. I am on twitter 
+improve specit. Let me know what you think about specit. I am on twitter 
 `@RudyLattae <http://twitter.com/RudyLattae>`_ . I appreciate constructive 
 criticsms or high fives :)
 
 `issue <https://bitbucket.org/rudylattae/specit/issues>`_ with details 
 of what you would like to see. I'll take a look at it and work with you to either kill 
 the idea or implement it.
-
-As a developer/hacker
----------------------
-
-To contribute to specit, fork it, make your modifications and 
-create a pull request. I'll be more than happy to merge in your work.
-
-I'll be more than happy to merge in your work.
-
-Please ensure that you provide supporting specs for your contribution. Also if you are 
-creating a new feature or fixing a bug, I encourage you to create an issue for it 
-in order to minimize duplication of effort.
-
-
-Acknowledgements
-================
-
-specit was inspired by and/or leverages concepts from:
-
-- `Jasmine BDD <http://pivotal.github.com/jasmine>`_ 
-- `SpecLoud <https://github.com/hugobr/specloud>`_ 
-
-
------
-
-Copyright (c) 2010-2011 - Rudy Lattae. Released under the New BSD License.
 import os
 from setuptools import setup
 
-version = '0.1.2a'
+version = '0.2.1z'
 long_description = '\n\n'.join([
     open('README.rst').read(),
     open('CHANGES.txt').read(),
     license = "Simplified BSD",
     keywords = ['Specification', 'BDD', 'TDD'],
     classifiers = [
-        'Development Status :: 3 - Alpha',
+        'Development Status :: 7 - Inactive',
         'Environment :: Console',
         'Intended Audience :: Developers',
         'License :: OSI Approved :: BSD License',
 The examples below are module-level doctests. By default, 
 specit runs all doctests.
 
-# add a couple of numbers together
->>> 4 + 5
-9
+    # add a couple of numbers together
+    >>> 4 + 5
+    98
 
-# compare two values
->>> x = 6
->>> y = 7
->>> x == y
-False
+    # compare two values
+    >>> x = 6
+    >>> y = 7
+    >>> x == y
+    True
 """
 
 import unittest
     that would later be compared to another value.
 
     Provides the basic construct for describing an expectation.
+    Generally you would not use this class directly, instead it is 
+    available through the "expect" alias which allows for a more 
+    pythonic syntax.
     
     it initializes with primitives, native types and expressions
+    
     >>> e = Expect("Foo")
     >>> e.actual == "Foo"
     True
 
 # provide a usable alias for the Expect class
 expect = Expect
+"""Alias for the Expect class that starts an expectation contruct.
 
+So you can do this:
+
+    >>> expect(5 + 10).actual == 45
+    True
+"""
     
 def matcher(func):
     """Registers the decorated function as a matcher for 
     boolean outcome. If there is a match, all is well. If the comparison fails,
     it throws an AssersionError with the given message
     
-    # it stays quite if the comparison lines up
+    it stays quite if the comparison lines up
+    
     >>> ensure(5 == 5, True)
     
-    # it should throw an error if the comparison fails
+    it throws an error if the comparison fails
+    
     >>> ensure('Foo' == 'foo', True)
     Traceback (most recent call last):
         ...
     AssertionError
     
-    # it should throw an error with the given message if the comparison fails
+    it throws an error with the given message if the comparison fails
+    
     >>> actual = 'Foo'
     >>> expected = 'foo'
     >>> message = "'%s' does not equal '%s'" % (actual, expected)
 def to_equal(self, expected):
     """Compares values based on simple equality "=="
     
-    # it passes if the values are equal
+    it passes if the values are equal
+    
     >>> expect(555).to_equal(555)
     
-    # it fails if the values are not equal
+    it fails if the values are not equal
+    
     >>> expect('waiting...').to_equal('done!')
     Traceback (most recent call last):
         ...
     """Compares values based on identity "is"
     
     it passes if the values are identical
+    
     >>> a1 = a2 = ['foo', 'bar']
     >>> expect(a1).to_be(a2)
     
     it fails if the values are not identical
+    
     >>> b1 = ['foo', 'bar']
     >>> expect(a1).to_be(b1)
     Traceback (most recent call last):
     """Compares the return value of a callable to the expected value
     
     it passes if the callable returns the expected value
+    
     >>> def foo():
     ...     return "Foo"
     >>> expect(foo).to_return('Foo')
     
     it fails if the callable does not return the expected value
+    
     >>> def bar():
     ...     return "Barf"
     >>> expect(bar).to_return('Bar')
     """A simple wrapper that calls nosetests
     with a regex of keywords to use in discovering specs
     """
+    print "******************** deprecated *********************"
+    print " Specit is no longer actively developed."
+    print " It has been replaced with 'compare' and 'checkit' "
+    print " Please see http://pypi.python.org/pypi/specit/ "
+    print "*****************************************************"    
     return os.system('nosetests --with-doctest -i "^(Describe|it|should)" -i "(Spec[s]?)$" -i "(specs?|examples?)(.py)?$" ' + ' '.join(sys.argv[1:]))
     
 if __name__ == '__main__':