"sysconfig" --- Fornece acesso às informações de configuração do Python
***********************************************************************

Novo na versão 3.2.

**Código-fonte:** Lib/sysconfig.py

======================================================================

O módulo "sysconfig" fornece acesso às informações de configuração do
Python, como a lista de caminhos de instalação e as variáveis de
configuração relevantes para a plataforma atual.


Variáveis de configuração
=========================

A Python distribution contains a "Makefile" and a "pyconfig.h" header
file that are necessary to build both the Python binary itself and
third-party C extensions compiled using "distutils".

"sysconfig" coloca todas as variáveis encontradas nestes arquivos em
um dicionário que pode ser acessado usando "get_config_vars()" ou
"get_config_var()".

Note que no Windows, é um conjunto muito menor.

sysconfig.get_config_vars(*args)

   Sem argumentos, retorna um dicionário de todas as variáveis de
   configuração relevantes para a plataforma atual.

   Com argumentos, retorna uma lista de valores resultantes da
   pesquisa de cada argumento no dicionário de variáveis de
   configuração.

   Para cada argumento, se o valor não for encontrado, retorna "None".

sysconfig.get_config_var(name)

   Retorna o valor de uma única variável *name*. Equivalente a
   "get_config_vars().get(name)".

   Se *name* não for encontrado, retorna "None".

Exemplo de uso:

   >>> import sysconfig
   >>> sysconfig.get_config_var('Py_ENABLE_SHARED')
   0
   >>> sysconfig.get_config_var('LIBDIR')
   '/usr/local/lib'
   >>> sysconfig.get_config_vars('AR', 'CXX')
   ['ar', 'g++']


Caminhos de instalação
======================

O Python usa um esquema de instalação que difere dependendo da
plataforma e das opções de instalação. Esses esquemas são armazenados
em "sysconfig" sob identificadores únicos baseados no valor retornado
por "os.name".

Every new component that is installed using "distutils" or a
Distutils-based system will follow the same scheme to copy its file in
the right places.

Python currently supports six schemes:

* *posix_prefix*: esquema para plataformas POSIX como Linux ou macOS.
  Este é o esquema padrão usado quando o Python ou um componente é
  instalado.

* *posix_home*: esquema para plataformas POSIX usado quando uma opção
  *home* é usada na instalação. Esse esquema é usado quando um
  componente é instalado por meio do Distutils com um prefixo inicial
  específico.

* *posix_user*: esquema para plataformas POSIX usado quando um
  componente é instalado através do Distutils e a opção *user* é
  usada. Esse esquema define caminhos localizados no diretório inicial
  do usuário.

* *nt*: esquema para plataformas NT como Windows.

* *nt_user*: esquema para plataformas NT, quando utilizada a opção
  *user*.

* *osx_framework_user*: esquema para plataformas macOS, quando
  utilizada a opção *user*.

Cada esquema é composto por uma série de caminhos e cada caminho
possui um identificador único. Python atualmente usa oito caminhos:

* *stdlib*: diretório que contém os arquivos da biblioteca Python
  padrão que não são específicos da plataforma.

* *platstdlib*: diretório que contém os arquivos da biblioteca Python
  padrão que são específicos da plataforma.

* *platlib*: diretório para arquivos específicos do site e específicos
  da plataforma.

* *purelib*: diretório para arquivos específicos do site e não
  específicos da plataforma.

* *include*: directory for non-platform-specific header files.

* *platinclude*: directory for platform-specific header files.

* *scripts*: diretório para arquivos de script.

* *data*: diretório para arquivos de dados.

"sysconfig" fornece algumas funções para determinar esses caminhos.

sysconfig.get_scheme_names()

   Retorna uma tupla contendo todos os esquemas atualmente suportados
   em "sysconfig".

sysconfig.get_default_scheme()

   Retorna o nome do esquema padrão para a plataforma atual.

   Novo na versão 3.10: Esta função era chamada de
   "_get_default_scheme()" e considerada um detalhe de implementação.

sysconfig.get_preferred_scheme(key)

   Retorna um nome de esquema preferido para um layout de instalação
   especificado por *key*.

   *key* deve ser ""prefix"", ""home"" ou ""user"".

   O valor de retorno é um nome de esquema listado em
   "get_scheme_names()". Ele pode ser passado para as funções
   "sysconfig" que recebem um argumento *scheme*, como "get_paths()".

   Novo na versão 3.10.

sysconfig._get_preferred_schemes()

   Retorna um dict contendo nomes de esquema preferidos na plataforma
   atual. Os implementadores e redistribuidores do Python podem
   adicionar seus esquemas preferidos ao valor global de nível de
   módulo "_INSTALL_SCHEMES" e modificar esta função para retornar
   esses nomes de esquema. Por exemplo, fornecer esquemas diferentes
   para os gerenciadores de pacotes de sistema e idioma usarem, de
   modo que os pacotes instalados por um não se misturem com os do
   outro.

   Os usuários finais não devem usar esta função, mas
   "get_default_scheme()" e "get_preferred_scheme()".

   Novo na versão 3.10.

sysconfig.get_path_names()

   Retorna uma tupla contendo todos os nomes de caminhos atualmente
   suportados em "sysconfig".

sysconfig.get_path(name[, scheme[, vars[, expand]]])

   Retorna um caminho de instalação correspondente ao caminho *name*,
   do esquema de instalação denominado *scheme*.

   *name* deve ser um valor da lista retornada por "get_path_names()".

   "sysconfig" armazena os caminhos de instalação correspondentes a
   cada nome de caminho, para cada plataforma, com variáveis a serem
   expandidas. Por exemplo, o caminho *stdlib* para o esquema *nt* é:
   "{base}/Lib".

   "get_path()" usará as variáveis retornadas por "get_config_vars()"
   para expandir o caminho. Todas as variáveis possuem valores padrão
   para cada plataforma, portanto, pode-se chamar esta função e obter
   o valor padrão.

   Se *scheme* for fornecido, deve ser um valor da lista retornada por
   "get_scheme_names()". Caso contrário, o esquema padrão para a
   plataforma atual é usado.

   If *vars* is provided, it must be a dictionary of variables that
   will update the dictionary return by "get_config_vars()".

   Se *expand* for definido como "False", o caminho não será expandido
   usando as variáveis.

   Se *name* não for encontrado, levanta uma "KeyError".

sysconfig.get_paths([scheme[, vars[, expand]]])

   Retorna um dicionário contendo todos os caminhos de instalação
   correspondentes a um esquema de instalação. Veja "get_path()" para
   mais informações.

   Se *esquema* não for fornecido, usará o esquema padrão para a
   plataforma atual.

   Se *vars* for fornecido, deve ser um dicionário de variáveis que
   atualizará o dicionário usado para expandir os caminhos.

   Se *expand* for definido como falso, os caminhos não serão
   expandidos.

   Se *scheme* não for um esquema existente, "get_paths()" vai
   levantar uma "KeyError".


Outras funções
==============

sysconfig.get_python_version()

   Retorna o número da versão Python "MAJOR.MINOR" como uma string.
   Semelhante a "'%d.%d' % sys.version_info[:2]".

sysconfig.get_platform()

   Retorna uma string que identifica a plataforma atual.

   Isso é usado principalmente para distinguir diretórios de
   construção específicos da plataforma e distribuições construídas
   específicas da plataforma. Geralmente inclui o nome e a versão do
   sistema operacional e a arquitetura (conforme fornecido por
   'os.uname()'), embora as informações exatas incluídas dependam do
   sistema operacional; por exemplo, no Linux, a versão do kernel não
   é particularmente importante.

   Exemplos de valores retornados:

   * linux-i586

   * linux-alpha (?)

   * solaris-2.6-sun4u

   Windows vai retornar um entre:

   * win-amd64 (Windows 64 bits no AMD64, isto é, x86_64, Intel64 e
     EM64T)

   * win32 (todos os demais - especificamente, sys.platform é
     retornado)

   macOS pode retornar:

   * macosx-10.6-ppc

   * macosx-10.4-ppc64

   * macosx-10.3-i386

   * macosx-10.4-fat

   Para outras plataformas não POSIX, é retornado apenas
   "sys.platform".

sysconfig.is_python_build()

   Retorna "True" se o interpretador Python em execução foi construído
   a partir do código-fonte e está sendo executado a partir de seu
   local de construção, e não de um local resultante de, por exemplo,
   executando "make install" ou instalando através de um instalador
   binário.

sysconfig.parse_config_h(fp[, vars])

   Analisa um arquivo no estilo "config.h".

   *fp* é um objeto arquivo ou similar apontando para o arquivo
   "config.h" ou similar.

   Um dicionário contendo pares nome/valor é retornado. Se um
   dicionário opcional for passado como segundo argumento, ele será
   usado no lugar de um novo dicionário e atualizado com os valores
   lidos no arquivo.

sysconfig.get_config_h_filename()

   Retorna o caminho do "pyconfig.h".

sysconfig.get_makefile_filename()

   Retorna o caminho do "Makefile".


Usando o módulo "sysconfig" como um Script
==========================================

Você pode usar "sysconfig" como um script com a opção *-m* do Python:

   $ python -m sysconfig
   Platform: "macosx-10.4-i386"
   Python version: "3.2"
   Current installation scheme: "posix_prefix"

   Paths:
           data = "/usr/local"
           include = "/Users/tarek/Dev/svn.python.org/py3k/Include"
           platinclude = "."
           platlib = "/usr/local/lib/python3.2/site-packages"
           platstdlib = "/usr/local/lib/python3.2"
           purelib = "/usr/local/lib/python3.2/site-packages"
           scripts = "/usr/local/bin"
           stdlib = "/usr/local/lib/python3.2"

   Variables:
           AC_APPLE_UNIVERSAL_BUILD = "0"
           AIX_GENUINE_CPLUSPLUS = "0"
           AR = "ar"
           ARFLAGS = "rc"
           ...

Esta chamada imprimirá na saída padrão as informações retornadas por
"get_platform()", "get_python_version()", "get_path()" e
"get_config_vars()".
