================
Welcome to pyloc
================

|ci-status| |cov| |version| |versions| |download| |stability| |license|

*pyloc* prints the location of the definition of any python object in
your file-system.

Introduction
============

*pyloc* is very similar to what ``python3 -m inspect -d <object>``
offers. However, it is only focused to retrieve the file name (and
eventually the line number) where a given Python object is defined.
The object can be a package, module, class, method or function.

*pyloc* makes some further efforts to figure out the line and column
number and its output is formatted so that it can easily be passed
to ``emacsclient`` or ``vi``.

Examples
========

You can see the location of ``Popen.wait`` method in the sub-process package:

.. code:: bash

    $ python -m pyloc -f human subprocess:Popen.wait
    Filename: /Users/polrop/.pyenv/versions/2.7.9/lib/python2.7/subprocess.py
    Line: 1379

    $ python -m pyloc -f human email.utils:formataddr
    Filename: /Users/polrop/.pyenv/versions/2.7.9/lib/python2.7/email/utils.py
    Line: 85

(Output may be different on your system if you have different
installation path and version)

Note that the object naming syntax is as follow: ``module[:qualname]``
Since version 0.2.0, syntax ``module[.qualname]`` a la pydoc is also
supported.

To open it in Emacs you can do:

.. code:: bash

    $ emacsclient `python -m pyloc -f emacs subprocess:Popen.wait`

or in vim:

.. code:: bash

    $ vim `python -m pyloc -f vi subprocess:Popen.wait`

If you are lazy typing ``-f <format>`` all the time and you often use
the same format, you can set the default output format this way (you
can add this line in your ``.zshenv`` or ``.bashrc``):

.. code:: bash

    $ export PYLOC_DEFAULT_FORMAT=emacs

*pyloc* will always locate object based on the ``python`` interpreter
your are using:

.. code:: bash

    $ python3 -m pyloc -f human subprocess:Popen.wait
    Filename: /Users/polrop/.pyenv/versions/3.4.3/lib/python3.4/subprocess.py
    Line: 1526

    $ /usr/local/bin/python -m pyloc -f human email.utils:formataddr
    Filename: /usr/local/Cellar/python/2.7.9/Frameworks/Python.framework/Versions/2.7/lib/python2.7/email/utils.py
    Line: 85

    $ /usr/bin/python -m pyloc -f human email.utils:formataddr
    Filename: /System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/email/utils.py
    Line: 85

Installation
============

Using pip
---------

You can install *pyloc* using ``pip`` like this:

.. code:: bash

    $ pip install pyloc

or

.. code:: bash

    $ pip3 install pyloc

Directly from the source
------------------------

.. code:: bash

    $ git clone https://github.com/nicolasdespres/pyloc.git
    $ cd pyloc
    $ python setup.py develop
    # If you also want it for Python 3
    $ python3 setup.py develop

Note that if you also install the Python 3 version, the ``pyloc2``
command line driver will not work but the ``pyloc`` driver will point
to the Python 2 installation.

To uninstall it, you ca do:

.. code:: bash

    $ python setup.py develop --uninstall
    # And if you installed the Python 3 version
    $ python3 setup.py develop --uninstall

However, this won't remove the entry scripts generated by easy
install.

Known bugs
==========

* Classes or built-in types like int or str do not contain location
  information. In this case *pyloc* tries to look for the name in the
  AST. This procedure may not be accurate since Python is a dynamic
  language.

Hacking
=======

See `HACKING <HACKING.rst>`_ for details.

Release notes
=============

See the corresponding tag annotation. After cloning you can do for instance:

.. code:: bash

    $ git show v0.1.10

License
=======

*pyloc* is released under the term of the
`Simplified BSD License <http://choosealicense.com/licenses/bsd-2-clause>`_.
Copyright (c) 2015-2106, Nicolas Desprès
All rights reserved.

As noted in the source code, some part has been inspired by code from
the ``inspect`` module written by Ka-Ping Yee <ping@lfw.org> and
Yury Selivanov <yselivanov@sprymix.com> form the Python 3.4.3
distribution (see the LICENSE file in the python distribution)





.. |ci-status| image:: https://api.travis-ci.org/nicolasdespres/pyloc.svg?branch=master
   :target: https://travis-ci.org/nicolasdespres/pyloc
   :alt: Build Status

.. |cov| image:: https://coveralls.io/repos/github/nicolasdespres/pyloc/badge.svg?branch=master
   :target: https://coveralls.io/github/nicolasdespres/pyloc?branch=master
   :alt: Coverage Status

.. |version| image:: https://img.shields.io/pypi/v/pyloc.svg
   :target: https://pypi.python.org/pypi/pyloc
   :alt: Last released version

.. |versions| image:: https://img.shields.io/pypi/pyversions/pyloc.svg
   :target: https://pypi.python.org/pypi/pyloc/
   :alt: Supported python versions

.. |download| image:: https://img.shields.io/pypi/dd/pyloc.svg
   :target: https://pypi.python.org/pypi/pyloc/
   :alt: Download rate

.. |stability| image:: https://img.shields.io/pypi/status/pyloc.svg
    :target: https://pypi.python.org/pypi/pyloc
    :alt: Package stability

.. |license| image:: https://img.shields.io/pypi/l/pyloc.svg
    :target: https://pypi.python.org/pypi/pyloc
    :alt: License
