# `site` — Gancho de configuração específico do site

Código-fonte: Lib/site.py

Este módulo é importado automaticamente durante a inicialização. A importação automática pode ser suprimida usando a opção `-S` do interpretador.

Importing this module normally appends site-specific paths to the module search path and adds callables, including `help()` to the built-in namespace. However, Python startup option `-S` blocks this, and this module can be safely imported with no automatic modifications to the module search path or additions to the builtins. To explicitly trigger the usual site-specific additions, call the `main()` function.

Alterado na versão 3.3: A importação do módulo usado para acionar a manipulação de caminhos, mesmo ao usar `-S`.

It starts by constructing up to four directories from a head and a tail part. For the head part, it uses `sys.prefix` and `sys.exec_prefix`; empty heads are skipped. For the tail part, it uses the empty string and then `lib/site-packages` (on Windows) or `lib/pythonX.Y[t]/site-packages` (on Unix and macOS). (The optional suffix “t” indicates the free-threaded build, and is appended if `"t"` is present in the `sys.abiflags` constant.) For each of the distinct head-tail combinations, it sees if it refers to an existing directory, and if so, adds it to `sys.path` and also inspects the newly added path for configuration files.

Alterado na versão 3.5: Suporte para o diretório “site-python” foi removido.

Alterado na versão 3.13: No Unix, as instalações do Python threads livres são identificadas pelo sufixo “t” no nome do diretório específico da versão, como `lib/python3.13t/`.

Alterado na versão 3.14: `site` is no longer responsible for updating `sys.prefix` and `sys.exec_prefix` on Ambientes virtuais. This is now done during the path initialization. As a result, under Ambientes virtuais, `sys.prefix` and `sys.exec_prefix` no longer depend on the `site` initialization, and are therefore unaffected by `-S`.

When running under a virtual environment, the `pyvenv.cfg` file in `sys.prefix` is checked for site-specific configurations. If the `include-system-site-packages` key exists and is set to `true` (case-insensitive), the system-level prefixes will be searched for site-packages, otherwise they won’t. If the system-level prefixes are not searched then the user site prefixes are also implicitly not searched for site-packages.

The `site` module recognizes two startup configuration files of the form `name.pth` for path configurations, and `name.start` for pre-first-line code execution. Both files can exist in one of the four directories mentioned above. Within each directory, these files are sorted alphabetically by filename, then parsed in sorted order.

## Path extensions (`.pth` files)

`name.pth` contains additional items (one per line) to be appended to `sys.path`. Items that name non-existing directories are never added to `sys.path`, and no check is made that the item refers to a directory rather than a file. No item is added to `sys.path` more than once. Blank lines and lines beginning with `#` are skipped.

For backward compatibility, lines starting with `import` (followed by space or tab) are executed with `exec()`.

Alterado na versão 3.13: Os arquivos `.pth` agora são decodificados primeiro por UTF-8 e depois pela codificação da localidade se falhar.

Alterado na versão 3.15: `.pth` file lines starting with `import` are deprecated. During the deprecation period, such lines are still executed (except in the case below), but a diagnostic message is emitted only when the `-v` flag is given.

`import` lines in `name.pth` are silently ignored when a matching `name.start` file exists.

Errors on individual lines no longer abort processing of the rest of the file. Each error is reported and the remaining lines continue to be processed.

Descontinuado desde a versão 3.15, será removido na versão 3.20: Decoding `name.pth` files in any encoding other than `utf-8-sig` is deprecated in Python 3.15, and support for decoding from the locale encoding will be removed in Python 3.20.

`import` lines in `name.pth` files are deprecated and will be silently ignored in Python 3.18 and 3.19. In Python 3.20 a warning will be produced for `import` lines in `name.pth` files.

## Startup entry points (`.start` files)

Adicionado na versão 3.15.

A startup entry point file is a file whose name has the form `name.start` and exists in one of the site-packages directories described above. Each file specifies entry points to be called during interpreter startup, using the `pkg.mod:callable` syntax understood by `pkgutil.resolve_name()`.

Each non-blank line that does not begin with `#` must contain an entry point reference in the form `pkg.mod:callable`. The colon and callable portion are mandatory. Each callable is invoked with no arguments, and any return value is discarded.

`.start` files are processed after all `.pth` path extensions have been applied to `sys.path`, ensuring that paths are available before any startup code runs.

Unlike `sys.path` extensions from `.pth` files, duplicate entry points are not de-duplicated — if an entry point appears more than once, it will be called more than once.

If an exception occurs during resolution or invocation of an entry point, a traceback is printed to `sys.stderr` and processing continues with the remaining entry points.

`.start` files must be encoded in UTF-8.

PEP 829 defined the original specification for these features.

Nota

If a `name.start` file exists alongside a `name.pth` file with the same base name, any `import` lines in the `.pth` file are ignored in favor of the entry points in the `.start` file.

Nota

Executable lines (`import` lines in `name.pth` files and `name.start` file entry points) are always run at Python startup (unless `-S` is given to disable the `site.py` module entirely), regardless of whether a particular module is actually going to be used.

Nota

`name.start` files invoke `pkgutil.resolve_name()` with `strict=True`, which requires the full `pkg.mod:callable` form.

## Startup file examples

For example, suppose `sys.prefix` and `sys.exec_prefix` are set to `/usr/local`. The Python X.Y library is then installed in `/usr/local/lib/pythonX.Y`. Suppose this has a subdirectory `/usr/local/lib/pythonX.Y/site-packages` with three sub-subdirectories, `foo`, `bar` and `spam`, and two path configuration files, `foo.pth` and `bar.pth`. Assume `foo.pth` contains the following:

    # configuração do pacote foo

    foo
    bar
    bletch

e que `bar.pth` contém:

    # configuração do pacote bar

    bar

Em seguida, os seguintes diretórios específicos da versão são adicionados a `sys.path`, nesta ordem:

    /usr/local/lib/pythonX.Y/site-packages/bar
    /usr/local/lib/pythonX.Y/site-packages/foo

Observe que `bletch` é omitido porque não existe; o diretório `bar` precede o diretório `foo` porque `bar.pth` vem em ordem alfabética antes de `foo.pth`; e `spam` é omitido porque não é mencionado em nenhum dos arquivos de configuração de caminho.

Let’s say that there is also a `foo.start` file containing the following:

    # foo package startup code

    foo.submod:initialize

Now, after `sys.path` has been extended as above, and before Python turns control over to user code, the `foo.submod` module is imported and the `initialize()` function from that module is called.

## Migrating from `import` lines in `.pth` files to `.start` files

If your package currently ships a `name.pth` file, you can keep all `sys.path` extension lines unchanged. Only `import` lines need to be migrated.

To migrate, create a callable (taking zero arguments) within an importable module in your package. Reference it as a `pkg.mod:callable` entry point in a matching `name.start` file. Move everything on your `import` line after the first semi-colon into the `callable()` function.

If your package must straddle older Pythons that do not support PEP 829 and newer Pythons that do, change the `import` lines in your `name.pth` to use the following form:

    import pkg.mod; pkg.mod.callable()

Older Pythons will execute these `import` lines, while newer Pythons will ignore them in favor of the `name.start` file. After the straddling period, remove all `import` lines from your `.pth` files.

## `sitecustomize`

After these path manipulations, an attempt is made to import a module named `sitecustomize`, which can perform arbitrary site-specific customizations. It is typically created by a system administrator in the site-packages directory. If this import fails with an `ImportError` or its subclass exception, and the exception’s `name` attribute equals `'sitecustomize'`, it is silently ignored. If Python is started without output streams available, as with `pythonw.exe` on Windows (which is used by default to start IDLE), attempted output from `sitecustomize` is ignored. Any other exception causes a silent and perhaps mysterious failure of the process.

## `usercustomize`

After this, an attempt is made to import a module named `usercustomize`, which can perform arbitrary user-specific customizations, if `ENABLE_USER_SITE` is true. This file is intended to be created in the user site-packages directory (see below), which is part of `sys.path` unless disabled by `-s`. If this import fails with an `ImportError` or its subclass exception, and the exception’s `name` attribute equals `'usercustomize'`, it is silently ignored.

Note that for some non-Unix systems, `sys.prefix` and `sys.exec_prefix` are empty, and the path manipulations are skipped; however the import of `sitecustomize` and `usercustomize` is still attempted.

## Configuração Readline

On systems that support `readline`, this module will also import and configure the `rlcompleter` module, if Python is started in interactive mode and without the `-S` option. The default behavior is to enable tab completion and to use `~/.python_history` as the history save file. To disable it, delete (or override) the `sys.__interactivehook__` attribute in your `sitecustomize` or `usercustomize` module or your `PYTHONSTARTUP` file.

Alterado na versão 3.4: A ativação do rlcompleter e do histórico foi feita automaticamente.

## Conteúdo do módulo

site.PREFIXES

  Uma lista de prefixos para diretórios site-package.

site.ENABLE_USER_SITE

  Sinalizador mostrando o status do diretório site-packages do usuário. `True` significa que ele está habilitado e foi adicionado a `sys.path`. `False` significa que ele foi desabilitado por solicitação do usuário (com `-s` ou `PYTHONNOUSERSITE`). `None` significa que ele foi desabilitado por motivos de segurança (incompatibilidade entre o ID do usuário ou grupo e o ID efetivo) ou por um administrador.

site.USER_SITE

  Caminho para o usuário site-packages para o Python em execução. Pode ser `None` se `getusersitepackages()` ainda não tiver sido chamado. O valor padrão é `~/.local/lib/pythonX.Y[t]/site-packages` para construções UNIX e macOS não-framework, `~/Library/Python/X.Y/lib/python/site-packages` para construções macOS framework e `%APPDATA%\Python\PythonXY\site-packages` no Windows. O “t” opcional indica a construção com threads livres. Este diretório é um diretório de site, o que significa que os arquivos `.pth` nele serão processados.

site.USER_BASE

  Caminho para o diretório base para os pacotes do site do usuário. Pode ser `None` se `getuserbase()` ainda não tiver sido chamado. O valor padrão é `~/.local` para construções não-framework UNIX e macOS, `~/Library/Python/X.Y` para construções de framework macOS e `%APPDATA%\Python` para Windows. Este valor é usado para calcular os diretórios de instalação para scripts, arquivos de dados, módulos Python, etc. para o esquema de instalação de usuário. Veja também `PYTHONUSERBASE`.

site.main()

  Adiciona todos os diretórios padrão específicos do site ao caminho de pesquisa de módulos. Esta função é chamada automaticamente quando este módulo é importado, a menos que o interpretador Python tenha sido iniciado com o sinalizador `-S`.

  Alterado na versão 3.3: Esta função costumava ser chamada incondicionalmente.

site.addsitedir(sitedir, known_paths=None, *, defer_processing_start_files=False)

  Add a directory to sys.path and parse the `.pth` and `.start` files found in that directory. Typically used in `sitecustomize` or `usercustomize` (see above).

  The known_paths argument is an optional set of case-normalized paths used to prevent duplicate `sys.path` entries. When `None` (the default), the set is built from the current `sys.path`.

  While `.pth` and `.start` files are always parsed, set defer_processing_start_files to `True` to prevent processing the startup data found in those files, so that you can process them explicitly (this is typically used by the `main()` function).

  Alterado na versão 3.15: Also processes `.start` files. See Startup entry points (.start files). All `.pth` and `.start` files are now read and accumulated before any path extensions, `import` line execution, or entry point invocations take place.

site.getsitepackages()

  Retorna uma lista contendo todos os diretórios globais de pacotes de sites.

  Adicionado na versão 3.2.

site.getuserbase()

  Retorna o caminho do diretório base do usuário, `USER_BASE`. Se ele ainda não foi inicializado, esta função também o definirá, respeitando `PYTHONUSERBASE`.

  Adicionado na versão 3.2.

site.getusersitepackages()

  Retorna o caminho do diretório site-packages específico do usuário, `USER_SITE`. Se ele ainda não foi inicializado, esta função também o definirá, respeitando `USER_BASE`. Para determinar se o site-packages específico do usuário foi adicionado a `sys.path`, `ENABLE_USER_SITE` deve ser usado.

  Adicionado na versão 3.2.

## Interface de linha de comando

The `site` module also provides a way to get the user directories from the command line:

    $ python -m site --user-site
    /home/user/.local/lib/python3.11/site-packages

Se for chamado sem argumentos, ele vai exibir o conteúdo de `sys.path` na saída padrão, seguido pelo valor de `USER_BASE` e se o diretório existe, depois o mesmo para `USER_SITE` e, finalmente, o valor de `ENABLE_USER_SITE`.

--user-base

  Exibe o caminho para o diretório base do usuário.

--user-site

  Exibe o caminho para o diretório site-packages do usuário.

Se ambas as opções forem fornecidas, a base do usuário e o site do usuário serão exibidos (sempre nesta ordem), separados por `os.pathsep`.

Se qualquer opção for fornecida, o script sairá com um destes valores: `0` se o diretório site-packages do usuário estiver habilitado, `1` se ele foi desabilitado pelo usuário, `2` se ele foi desabilitado por motivos de segurança ou por um administrador, e um valor maior que 2 se houver um erro.

Ver também

- PEP 370 – Diretório site-packages por usuário.

- PEP 829 – Startup entry points and the deprecation of import lines in `.pth` files

- A inicialização do caminho de pesquisa de módulos sys.path – A inicialização de `sys.path`.