Skip to content

README: Update formatting and links #265

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mpirnat merged 1 commit into from
Dec 20, 2022
Merged

README: Update formatting and links #265

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 51 additions & 43 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,10 +32,14 @@ language by making tests pass.

Most tests are *fixed* by filling the missing parts of assert functions. Eg:

.. code-block:: python

self.assertEqual(__, 1+2)

which can be fixed by replacing the __ part with the appropriate code:

.. code-block:: python

self.assertEqual(3, 1+2)

Occasionally you will encounter some failing tests that are already filled out.
Expand All @@ -50,11 +54,11 @@ a taste of Test Driven Development (TDD).
Downloading Python Koans
------------------------

Python Koans is available through git on Github:
Python Koans is available on GitHub:

http://github.com/gregmalcolm/python_koans
* https://github.com/gregmalcolm/python_koans

Either site will allow you to download the source as a zip/gz/bz2.
You can clone with Git or download the source as a zip/gz/bz2.


Installing Python Koans
Expand All @@ -63,25 +67,25 @@ Installing Python Koans
Aside from downloading or checking out the latest version of Python Koans, you
need to install the Python interpreter.

At this time of writing, we support Python3. The policy is to try to keep
At this time of writing, we support Python 3. The policy is to try to keep
current with the latest production version.

You should be able to work with newer Python versions, but older ones will
likely give you problems.

You can download Python from here:

http://www.python.org/download
* https://www.python.org/downloads/

After installing Python make sure the folder containing the python executable
is in the system path. In other words, you need to be able to run Python from a
command console. It will either be `python3` or for windows it will be `python.exe`.
command console. It will either be ``python3`` or for Windows it will be ``python.exe``.

If you have problems, this may help:

http://www.python.org/about/gettingstarted
* https://www.python.org/about/gettingstarted/

Windows users may also want to update the line in the batch file `run.bat` to
Windows users may also want to update the line in the batch file ``run.bat`` to
set the python path::

SET PYTHON_PATH=C:\Python39
Expand All @@ -92,19 +96,23 @@ Getting Started

Jake Hebbert has created a couple of screencasts available here:

http://www.youtube.com/watch?v=e2WXgXEjbHY&list=PL5Up_u-XkWgNcunP_UrTJG_3EXgbK2BQJ&index=1
https://www.youtube.com/watch?v=e2WXgXEjbHY&list=PL5Up_u-XkWgNcunP_UrTJG_3EXgbK2BQJ&index=1

Or if you prefer to read:

From a \*nix terminal or windows command prompt run::
From a \*nix terminal or Windows command prompt run::

.. code-block:: sh

python contemplate_koans.py

or::
or:

.. code-block:: sh

python3 contemplate_koans.py

In my case I'm using Python 3 with windows, so I fire up my command
In my case I'm using Python 3 with Windows, so I fire up my command
shell (cmd.exe) and run this:

.. image:: https://user-images.githubusercontent.com/2614930/28401747-f723ff00-6cd0-11e7-9b9a-a6993b753cf6.png
Expand All @@ -114,11 +122,13 @@ Apparently a test failed::
AssertionError: False is not True

It also tells me exactly where the problem is, it's an assert on line 12
of .\\koans\\about_asserts.py. This one is easy, just change False to True to
of ``.\\koans\\about_asserts.py``. This one is easy, just change ``False`` to ``True`` to
make the test pass.

Sooner or later you will likely encounter tests where you are not sure what the
expected value should be. For example::
expected value should be. For example:

.. code-block:: python

class Dog:
pass
Expand All @@ -138,40 +148,51 @@ Sniffer Support
Sniffer allows you to run the tests continuously. If you modify any files files
in the koans directory, it will rerun the tests.

To set this up, you need to install sniffer::
To set this up, you need to install sniffer:

.. code-block:: sh

$ pip install sniffer
python3 -m pip install sniffer

You should also run one of these libraries depending on your system. This will
automatically trigger sniffer when a file changes, otherwise sniffer will have
to poll to see if the files have changed.

On Linux::
On Linux:

.. code-block:: sh

$ pip install pyinotify
python3 -m pip install pyinotify

On Windows::
On Windows:

$ pip install pywin32
.. code-block:: sh

python3 -m pip install pywin32

Also available here:

https://github.com/mhammond/pywin32/releases

On Mac OS X::
On macOS:

.. code-block:: sh

python3 -m pip install MacFSEvents

$ pip install MacFSEvents
Once it is set up, you just run:

Once it is set up, you just run::
.. code-block:: sh

$ sniffer
sniffer

Just modify one of the koans files and you'll see that the tests are triggered automatically. Sniffer is controlled by `scent.py`
Just modify one of the koans files and you'll see that the tests are triggered
automatically. Sniffer is controlled by ``scent.py``.

Getting the Most From the Koans
-------------------------------

Quoting the Ruby Koans instructions::
Quoting the Ruby Koans instructions:

"In test-driven development the mantra has always been, red, green,
refactor. Write a failing test and run it (red), make the test pass
Expand All @@ -182,28 +203,15 @@ Quoting the Ruby Koans instructions::
and improve the code to better communicate its intent (refactor)."


Content
-------

The Python Koans is a made up of about 2/3 Ruby Koans ported material and 1/3
Python specific tests. The content ported from Ruby Koans includes all the
assignment projects.

Content for Python 3 is a little different to the Python 2 flavor due to big
changes between the two different versions of the language. For example, in
the Python 2 variant the differences between old and new style classes are
covered. This loses relevance in in the Python 3 version, but there are some
extra tests covering new functionality.


Finding More Koan Projects
--------------------------

There are number of other great Koan projects out there for various languages
and frameworks. Most of them can be found in github. Also there is a little
koans activity on bitbucket.
and frameworks. Most of them can be found in GitHub. Also there is a little
koans activity on Bitbucket.

* Github koan projects:
* GitHub koan projects:
https://github.com/search?q=koans&ref=cmdform

* Bitbucket koan projects:
Expand All @@ -228,7 +236,7 @@ Also thanks to everyone who has contributed to Python Koans! I got a great
headstart by taking over a code base initiated by the combined Mikes of
FPIP. So here's a little plug for their very cool Python podcast:

http://frompythonimportpodcast.com/
* https://www.frompythonimportpodcast.com/

A big thanks also to Mike Pirnat @pirnat and Kevin Chase @kjc have pitched in
as co-maintainers at various times