11.2. "os.path" --- Manipulações comuns de nome nomes de caminhos
*****************************************************************

**Código Fonte:** Lib/posixpath.py (for POSIX), Lib/ntpath.py (for
Windows NT), and Lib/macpath.py (for Macintosh)

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

Este módulo implementa algumas funções úteis em nomes de caminho. Para
ler ou escrever arquivos, veja "open()", e para acessar o sistema de
arquivos veja o módulo "os". Os parâmetros de caminho podem ser
passados como strings ou bytes. As aplicações são encorajadas a
representar nomes de arquivos como strings de caracteres (Unicode).
Infelizmente, alguns nomes de arquivo podem não ser representados como
strings no Unix, então as aplicações que precisam ter suporte a nomes
de arquivo arbitrários no Unix devem usar objetos bytes para
representar nomes de caminho. Vice-versa, usar objetos bytes não pode
representar todos os nomes de arquivos no Windows (na codificação
"mbcs" padrão), portanto, as aplicações do Windows devem usar objetos
string para acessar todos os arquivos.

Ao contrário de um shell Unix, Python não faz nenhuma expansão
*automática* de caminho. Funções como "expanduser()" e "expandvars()"
podem ser invocadas explicitamente quando uma aplicação deseja uma
expansão de caminho no estilo do shell. (Veja também o módulo "glob".)

Ver também:

  O módulo "pathlib" oferece objetos de caminho de alto nível.

Nota:

  Todas essas funções aceitam apenas bytes ou apenas objetos de string
  como seus parâmetros. O resultado é um objeto do mesmo tipo, se um
  caminho ou nome de arquivo for retornado.

Nota:

  Uma vez que diferentes sistemas operacionais têm diferentes
  convenções de nome de caminho, existem várias versões deste módulo
  na biblioteca padrão. O módulo "os.path" é sempre o módulo de
  caminho adequado para o sistema operacional em que o Python está
  sendo executado e, portanto, pode ser usado para caminhos locais. No
  entanto, você também pode importar e usar os módulos individuais se
  quiser manipular um caminho que esteja *sempre* em um dos diferentes
  formatos. Todos eles têm a mesma interface:

  * "posixpath" para caminhos no estilo UNIX

  * "ntpath" para caminhos do Windows

  * "macpath" for old-style MacOS paths

os.path.abspath(path)

   Retorna uma versão normalizada e absolutizada do nome de caminho
   *path*. Na maioria das plataformas, isso é equivalente a chamar a
   função "normpath()" da seguinte forma: "normpath(join(os.getcwd(),
   path))".

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.basename(path)

   Retorna o nome base do caminho *path*. Este é o segundo elemento do
   par retornado pela passagem de *path* para a função "split()".
   Observe que o resultado desta função é diferente do programa Unix
   **basename**; onde **basename** para "'/foo/bar/'" retorna "'bar'",
   a função "basename()" retorna uma string vazia ("''").

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.commonpath(paths)

   Return the longest common sub-path of each pathname in the sequence
   *paths*.  Raise ValueError if *paths* contains both absolute and
   relative pathnames, or if *paths* is empty.  Unlike
   "commonprefix()", this returns a valid path.

   Disponibilidade: Unix, Windows

   Novo na versão 3.5.

   Alterado na versão 3.6: Aceita uma sequência de *objetos caminho ou
   similar*.

os.path.commonprefix(list)

   Retorna o prefixo de caminho mais longo (obtido caractere por
   caractere) que é um prefixo de todos os caminhos em *list*. Se
   *list* estiver vazia, retorna a string vazia ("''").

   Nota:

     Esta função pode retornar caminhos inválidos porque funciona um
     caractere por vez. Para obter um caminho válido, consulte
     "commonpath()".

        >>> os.path.commonprefix(['/usr/lib', '/usr/local/lib'])
        '/usr/l'

        >>> os.path.commonpath(['/usr/lib', '/usr/local/lib'])
        '/usr'

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.dirname(path)

   Retorna o nome do diretório do nome de caminho *path*. Este é o
   primeiro elemento do par retornado passando *path* para a função
   "split()".

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.exists(path)

   Retorna "True" se *path* se referir a um caminho existente ou um
   descritor de arquivo aberto. Retorna "False" para links simbólicos
   quebrados. Em algumas plataformas, esta função pode retornar
   "False" se a permissão não for concedida para executar "os.stat()"
   no arquivo solicitado, mesmo se o *path* existir fisicamente.

   Alterado na versão 3.3: *path* agora pode ser um inteiro: "True" é
   retornado se for um descritor de arquivo aberto, "False" caso
   contrário.

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.lexists(path)

   Retorna "True" se *path* se referir a um caminho existente. Retorna
   "True" para links simbólicos quebrados. Equivalente a "exists()" em
   plataformas sem "os.lstat()".

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.expanduser(path)

   No Unix e no Windows, retorna o argumento com um componente inicial
   de "~" ou "~user" substituído pelo diretório inicial daquele
   usuário *user*.

   No Unix, um "~" no início é substituído pela variável de ambiente
   "HOME" se estiver definida; caso contrário, o diretório pessoal do
   usuário atual é procurado no diretório de senha através do módulo
   embutido "pwd". Um "~user" no início é procurado diretamente no
   diretório de senhas.

   On Windows, "HOME" and "USERPROFILE" will be used if set, otherwise
   a combination of "HOMEPATH" and "HOMEDRIVE" will be used.  An
   initial "~user" is handled by stripping the last directory
   component from the created user path derived above.

   Se a expansão falhar ou se o caminho não começar com um til, o
   caminho será retornado inalterado.

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.expandvars(path)

   Retorna o argumento com as variáveis de ambiente expandidas.
   Substrings da forma "$name" ou "${name}" são substituídas pelo
   valor da variável de ambiente *name*. Nomes de variáveis
   malformados e referências a variáveis não existentes permanecem
   inalterados.

   No Windows, expansões "%name%" são suportadas juntamente a "$name"
   e "${name}".

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.getatime(path)

   Return the time of last access of *path*.  The return value is a
   number giving the number of seconds since the epoch (see the
   "time" module).  Raise "OSError" if the file does not exist or is
   inaccessible.

   If "os.stat_float_times()" returns "True", the result is a floating
   point number.

os.path.getmtime(path)

   Return the time of last modification of *path*.  The return value
   is a number giving the number of seconds since the epoch (see the
   "time" module). Raise "OSError" if the file does not exist or is
   inaccessible.

   If "os.stat_float_times()" returns "True", the result is a floating
   point number.

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.getctime(path)

   Retorna o ctime do sistema que, em alguns sistemas (como Unix) é a
   hora da última alteração de metadados, e, em outros (como Windows),
   é a hora de criação de *path*. O valor de retorno é um número que
   fornece o número de segundos desde a Era Unix (veja o módulo
   "time"). Levanta "OSError" se o arquivo não existe ou está
   inacessível.

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.getsize(path)

   Retorna o tamanho, em bytes, de *path*. Levanta "OSError" se o
   arquivo não existe ou está inacessível.

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.isabs(path)

   Retorna "True" se *path* for um nome de caminho absoluto. No Unix,
   isso significa que começa com uma barra, no Windows começa com uma
   barra (invertida) depois de eliminar uma possível letra de unidade.

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.isfile(path)

   Retorna "True" se *path* for um arquivo regular "existente". Isso
   segue links simbólicos, então "islink()" e "isfile()" podem ser
   verdadeiros para o mesmo caminho.

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.isdir(path)

   Retorna "True" se *path* for um diretório "existente". Isso segue
   links simbólicos, então "islink()" e "isdir()" podem ser
   verdadeiros para o mesmo caminho.

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.islink(path)

   Retorna "True" se *path* se referir a uma entrada de diretório
   "existente" que é um link simbólico. Sempre "False" se links
   simbólicos não forem suportados pelo tempo de execução Python.

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.ismount(path)

   Return "True" if pathname *path* is a *mount point*: a point in a
   file system where a different file system has been mounted.  On
   POSIX, the function checks whether *path*'s parent, "path/..", is
   on a different device than *path*, or whether "path/.." and *path*
   point to the same i-node on the same device --- this should detect
   mount points for all Unix and POSIX variants.  On Windows, a drive
   letter root and a share UNC are always mount points, and for any
   other path "GetVolumePathName" is called to see if it is different
   from the input path.

   Novo na versão 3.4: Suporte para detecção de pontos de montagem não
   raiz no Windows.

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.join(path, *paths)

   Junta um ou mais componentes do caminho de forma inteligente. O
   valor de retorno é a concatenação de *path* e qualquer membro de
   **paths* com exatamente um separador de diretório ("os.sep")
   seguindo cada parte não vazia exceto a última, o que significa que
   o resultado só terminará em um separador se a última parte estiver
   vazia. Se um componente for um caminho absoluto, todos os
   componentes anteriores serão descartados e a união continuará a
   partir do componente do caminho absoluto.

   No Windows, a letra da unidade não é redefinida quando um
   componente de caminho absoluto (por exemplo, "r'\foo'") é
   encontrado. Se um componente contiver uma letra de unidade, todos
   os componentes anteriores serão descartados e a letra da unidade
   será redefinida. Observe que, como há um diretório atual para cada
   unidade, "os.path.join("c:", "foo")" representa um caminho relativo
   ao diretório atual na unidade "C:" ("c:foo"), e não "c:\foo".

   Alterado na versão 3.6: Aceita um *objeto caminho ou similar* para
   *path* e *paths*.

os.path.normcase(path)

   Normalize the case of a pathname.  On Unix and Mac OS X, this
   returns the path unchanged; on case-insensitive filesystems, it
   converts the path to lowercase.  On Windows, it also converts
   forward slashes to backward slashes. Raise a TypeError if the type
   of *path* is not "str" or "bytes" (directly or indirectly through
   the "os.PathLike" interface).

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.normpath(path)

   Normaliza um nome de caminho retirando separadores redundantes e
   referências de nível superior para que "A//B", "A/B/", "A/./B" e
   "A/foo/../B" todos se tornem "A/B". Essa manipulação de string pode
   mudar o significado de um caminho que contém links simbólicos. No
   Windows, ele converte barras normais em barras invertidas. Para
   normalizar o estado de letras maiúsculas/minúsculas, use
   "normcase()".

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.realpath(path)

   Retorna o caminho canônico do nome do arquivo especificado,
   eliminando quaisquer links simbólicos encontrados no caminho (se
   esses forem suportados pelo sistema operacional).

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.relpath(path, start=os.curdir)

   Retorna um caminho de arquivo relativo a *caminho* do diretório
   atual ou de um diretório *start* opcional. Este é um cálculo de
   caminho: o sistema de arquivos não é acessado para confirmar a
   existência ou natureza de *path* ou *start*.

   *start* tem como padrão "os.curdir".

   Disponibilidade: Unix, Windows.

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.samefile(path1, path2)

   Retorna "True" se ambos os argumentos de nome de caminho se referem
   ao mesmo arquivo ou diretório. Isso é determinado pelo número do
   dispositivo e número do nó-i e levanta uma exceção se uma chamada
   "os.stat()" em qualquer um dos caminhos falhar.

   Disponibilidade: Unix, Windows.

   Alterado na versão 3.2: Adicionado suporte ao Windows.

   Alterado na versão 3.4: O Windows agora usa a mesma implementação
   que todas as outras plataformas.

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.sameopenfile(fp1, fp2)

   Retorna "True" se os descritores de arquivo *fp1* e *fp2* fazem
   referência ao mesmo arquivo.

   Disponibilidade: Unix, Windows.

   Alterado na versão 3.2: Adicionado suporte ao Windows.

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.samestat(stat1, stat2)

   Retorna "True" se as tuplas de estatísticas *stat1* e *stat2* fazem
   referência ao mesmo arquivo. Essas estruturas podem ter sido
   retornadas por "os.fstat()", "os.lstat()" ou "os.stat()". Esta
   função implementa a comparação subjacente usada por "samefile()" e
   "sameopenfile()".

   Disponibilidade: Unix, Windows.

   Alterado na versão 3.4: Adicionado suporte ao Windows.

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.split(path)

   Divide o caminho *path* em um par, "(cabeça, rabo)" onde *rabo* é o
   último componente do nome do caminho e *cabeça* é tudo o que leva a
   isso. A parte *rabo* nunca conterá uma barra; se *path* terminar
   com uma barra, *tail* ficará vazio. Se não houver uma barra no
   *path*, o *head* ficará vazio. Se *path* estiver vazio, *cabeça* e
   *rabo* estarão vazios. As barras finais são retiradas da *cabeça*,
   a menos que seja a raiz (uma ou mais barras apenas). Em todos os
   casos, "join(cabeça, rabo)" retorna um caminho para o mesmo local
   que *path* (mas as strings podem ser diferentes). Veja também as
   funções "dirname()" e "basename()".

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.splitdrive(path)

   Divide o nome do caminho *path* em um par "(unidade, rabo)" onde
   *unidade* é um ponto de montagem ou uma string vazia. Em sistemas
   que não usam especificações de unidade, *unidade* sempre será a
   string vazia. Em todos os casos, "unidade + rabo" será o mesmo que
   *path*.

   No Windows, divide um nome de caminho em unidade/ponto de
   compartilhamento UNC e caminho relativo.

   Se o caminho contiver uma letra de unidade, a unidade conterá tudo,
   até e incluindo os dois pontos, por exemplo, "splitdrive("c:/dir")"
   retorna "("c:", "/dir")"

   Se o caminho contiver um caminho UNC, a unidade conterá o nome do
   host e o compartilhamento, até mas não incluindo o quarto
   separador. por exemplo, "splitdrive("//host/computer/dir")" retorna
   "("//host/computer", "/dir")"

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.splitext(path)

   Divide o nome de caminho *path* em um par "(root, ext)" de tal
   forma que "root + ext == path", e *ext* esteja vazio ou inicia com
   um ponto e contém no máximo um ponto. Pontos no início do nome base
   são ignorados; "splitext('.cshrc')" retorna  "('.cshrc', '')".

   Alterado na versão 3.6: Aceita um *path-like object*.

os.path.splitunc(path)

   Obsoleto desde a versão 3.1: Use *splitdrive* instead.

   Split the pathname *path* into a pair "(unc, rest)" so that *unc*
   is the UNC mount point (such as "r'\\host\mount'"), if present, and
   *rest* the rest of the path (such as  "r'\path\file.ext'").  For
   paths containing drive letters, *unc* will always be the empty
   string.

   Availability:  Windows.

os.path.supports_unicode_filenames

   "True" se strings Unicode arbitrárias podem ser usadas como nomes
   de arquivo (dentro das limitações impostas pelo sistema de
   arquivos).
