<commit_before>The relative_import utility
===========================

Relative import tool for running subpackages or submodules as main scripts (enabling relative imports)


How do you use it?
------------------
Imagine you have 2 modules inside a package called "my_pkg".

That would be:

* my_pkg/math_lib.py
* my_pkg/test.py

So in test.py we could have

```python
from .math_lib import factorize

def print_factorize(number):
    num = factorize(number)
    print num

if __name__ == '__main__':
    #Small smoke test
    factorize_and_print(10)
    factorize_and_print(0)
    factorize_and_print(-10)
```
If you do "python my_pkg/test.py" it will throw an exception because of the relative import at the first line.

PEP 366 presents a workaround like:
```python
if __name__ == "__main__" and __package__ is None:
    __package__ = "my_pkg"

from .math_lib import factorize

```

This will make the code work, but it is not an elegant solution. 

So you can use **relative_import** to make your code look nicer like.
```python
import relative_import
from .math_lib import factorize

```

How does it work?
-----------------

The solution uses the same technique in PEP 366, but setting __package__ through dynamic inspection of the stack. To solve the value of __package__ it compares the current `__main__`'s file with paths at sys.path -or, optionally, a list of paths given in the preferences-.

For example, for a file in **/home/user/projects/python/math/my_pkg/test.py** given the following paths in sys.path:
```python
[
'/home/user/projects/python/',
'/home/user/projects/python/math/',
'/home/user/projects/python/math/my_pkg/',
]
```
It will pick the closest path to the `__main__`'s file that is not the `__main__`'s file's directory.

Then the base path use to solve __package__ variable will be **/home/user/projects/python/math/**

Preferences
-----------
This package works out-of-the-box without any configuration, but you can set certain preferences.

To do so, create a relative_import_settings.py in one of your PYTHON_PATHs. Should be like

```python

class Settings(object):
    #Self explanatory
    relative_import_enabled = True
    #instead of searching in sys.path, use this list
    #beware, if empty, it will look into sys.path anyway
    relative_import_path = ['/some/path/to/project/']

```

Related PEPs
------------

* http://legacy.python.org/dev/peps/pep-0328/
* http://legacy.python.org/dev/peps/pep-0366/
<commit_msg>Fix documentation<commit_after>The relative_import utility
===========================

Relative import tool for running subpackages or submodules as main scripts (enabling relative imports)


How to use it?
--------------

Imagine you have 2 modules inside a package called "my_pkg".

That would be:

* my_pkg/__init__.py
* my_pkg/math_lib.py
* my_pkg/test.py

So in test.py we could have

```python
from .math_lib import factorize

def print_factorize(number):
    num = factorize(number)
    print num

if __name__ == '__main__':
    #Small smoke test
    factorize_and_print(10)
    factorize_and_print(0)
    factorize_and_print(-10)
```
If you do `python my_pkg/test.py` it will throw an exception because of the relative import at the first line.

PEP 366 presents a workaround like:
```python
if __name__ == "__main__" and __package__ is None:
    __package__ = "my_pkg"

from .math_lib import factorize

```

This will make the code work, but it is not an elegant solution. 

So you can use `relative_import` to make your code look nicer like. Simply do:
```python
import relative_import
from .math_lib import factorize

```
It is equivalent as the PEP's solution but you don't have to worry about keeping in sync `__package__`'s value

How does it work?
-----------------

It uses the same technique in PEP 366 but `__package__`'s value is set through dynamic inspection of the stack. To solve the value of __package__ it compares the current `__main__`'s file with paths in sys.path - or, optionally, a list of paths given in the preferences-.

For example, for a file in `/home/user/projects/python/math/my_pkg/test.py` given the following paths in sys.path:
```python
[
'/home/user/projects/python/',
'/home/user/projects/python/math/',
'/home/user/projects/python/math/my_pkg/',
]
```
It will pick the closest path to the `__main__`'s file that is not the `__main__`'s file's directory.

Then the base path use to solve __package__ variable will be **/home/user/projects/python/math/**

Preferences
-----------

This package works out-of-the-box without any configuration, but you can set certain preferences.

To do so, create a relative_import_settings.py in one of your PYTHON_PATHs. Should be like

```python

class Settings(object):
    #Self explanatory
    relative_import_enabled = True
    #instead of searching in sys.path, use this list
    #beware, if empty, it will look into sys.path anyway
    relative_import_path = ['/some/path/to/project/']

```

Related PEPs
------------

* http://legacy.python.org/dev/peps/pep-0328/
* http://legacy.python.org/dev/peps/pep-0366/

{'fraction_non_alphanumeric': 0.11956521739130435, 'fraction_numerical': 0.007905138339920948, 'mean_word_length': 3.6948051948051948, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '388738', 'n_tokens_mistral': 1601, 'n_tokens_neox': 1522, 'n_words': 595}