Here is another alternative that I insert at top of the Python files in tests folder:

# Path hack.
import sys, os
sys.path.insert(0, os.path.abspath('..'))

You don’t need and shouldn’t hack sys.path unless it is necessary and in this case it is not. Use:

import api.api_key # In tests, examples

Run from the project directory: python -m tests.test_one.

You should probably move tests (if they are api‘s unittests) inside api and run python -m api.test to run all tests (assuming there is __main__.py) or python -m api.test.test_one to run test_one instead.

You could also remove __init__.py from examples (it is not a Python package) and run the examples in a virtualenv where api is installed, e.g., pip install -e . in a virtualenv would install in place api package if you have a proper setup.py.

For readers in 2023: If you’re not confident with pip install -e :

TL;DR: A script (usually an entry point) can only import anything the same or below its level.

Consider this hierarchy, as recommended by an answer from Relative imports in Python 3:

MyProject
├── src
│   ├── bot
│   │   ├── __init__.py
│   │   ├── main.py
│   │   └── sib1.py
│   └── mod
│       ├── __init__.py
│       └── module1.py
└── main.py

To run our program from the starting point with the simple command python main.py, we use absolute import (no leading dot(s)) in main.py here:

from src.bot import main


if __name__ == '__main__':
    main.magic_tricks()

The content of bot/main.py, which takes advantage of explicit relative imports to show what we’re importing, looks like this:

from .sib1 import my_drink                # Both are explicit-relative-imports.
from ..mod.module1 import relative_magic

def magic_tricks():
    # Using sub-magic
    relative_magic(in=["newbie", "pain"], advice="cheer_up")
    
    my_drink()
    # Do your work
    ...

These are the reasoning:

• We don’t want to give “OK, so this is a module” a funk when we want to run our Python program, sincerely.
  • So we use absolute import for the entry point main.py, this way we can run our program by simply python main.py.
  • Behind the scene, Python will use sys.path to resolve packages for us, but this also means that the package we want to import can probably be superseded by any other package of the same name due to the ordering of paths in sys.path, e.g., try import test.
• To avoid those conflicts, we use explicit relative import.
  • The from ..mod syntax makes it very clear about “we’re importing our own local package”.
  • But the drawback is that you need to think about “OK, so this is a module” again when you want to run the module as a script.
• Finally, the from ..mod  part means that it will go up one level to MyProject/src.

Conclusion

1. Put your main.py script next to the root of all your packages MyProject/src, and use absolute import in python main.py to import anything. No one will create a package named src.
2. Those explicit relative imports will just work.
3. To run a module, use python -m ....

Appendix: More about running any file under src/ as a script?

Then you should use the syntax python -m  and take a look at my other post: ModuleNotFoundError: No module named ‘sib1’

I don’t yet have the comprehension of Pythonology necessary to see the intended way of sharing code amongst unrelated projects without a sibling/relative import hack. Until that day, this is my solution. For examples or tests to import stuff from ..\api, it would look like:

import sys.path
import os.path
# Import from sibling directory ..\api
sys.path.append(os.path.dirname(os.path.abspath(__file__)) + "/..")
import api.api
import api.api_key

For siblings package imports, you can use either the insert or the append method of the sys.path module:

if __name__ == '__main__' and if __package__ is None:
    import sys
    from os import path
    sys.path.append( path.dirname( path.dirname( path.abspath(__file__) ) ) )
    import api

This will work if you are launching your scripts as follows:

python examples/example_one.py
python tests/test_one.py

On the other hand, you can also use the relative import:

if __name__ == '__main__' and if __package__ is not None:
    import ..api.api

In this case you will have to launch your script with the ‘-m’ argument (note that, in this case, you must not give the ‘.py’ extension):

python -m packageName.examples.example_one
python -m packageName.tests.test_one

Of course, you can mix the two approaches, so that your script will work no matter how it is called:

if __name__ == '__main__':
    if __package__ is None:
        import sys
        from os import path
        sys.path.append( path.dirname( path.dirname( path.abspath(__file__) ) ) )
        import api
    else:
        import ..api.api

You need to look to see how the import statements are written in the related code. If examples/example_one.py uses the following import statement:

import api.api

…then it expects the root directory of the project to be in the system path.

The easiest way to support this without any hacks (as you put it) would be to run the examples from the top level directory, like this:

PYTHONPATH=$PYTHONPATH:. python examples/example_one.py 

Just in case someone using PyDev on Eclipse end up here: you can add the sibling’s parent path (and thus the calling module’s parent) as an external library folder using Project->Properties and setting External Libraries under the left menu Pydev-PYTHONPATH.

Then you can import from your sibling, for example, from sibling import some_class.

I wanted to comment on the solution provided by np8, but I don’t have enough reputation, so I’ll just mention that you can create a setup.py file exactly as they suggested, and then do pipenv install --dev -e . from the project root directory to turn it into an editable dependency.

Then your absolute imports will work, e.g., from api.api import foo, and you don’t have to mess around with system-wide installations.

Documentation

If you’re using pytest then the pytest documentation describes a method of how to reference source packages from a separate test package.

The suggested project directory structure is:

setup.py
src/
    mypkg/
        __init__.py
        app.py
        view.py
tests/
    __init__.py
    foo/
        __init__.py
        test_view.py
    bar/
        __init__.py
        test_view.py

Contents of the setup.py file:

from setuptools import setup, find_packages

setup(name="PACKAGENAME", packages=find_packages())

Install the packages in editable mode:

pip install -e .

The pytest article references this blog post by Ionel Cristian Mărieș.

I made a sample project to demonstrate how I handled this, which is indeed another sys.path hack as indicated above. Python Sibling Import Example, which relies on:

if __name__ == '__main__': import os import sys sys.path.append(os.getcwd())

This seems to be pretty effective so long as your working directory remains at the root of the Python project.