Esta documentação é de uma versão antiga do Python que não é mais atualizada. Você deveria atualizar e ler a Documentação do Python para versão estável atual.

# `os.path` — Manipulações comuns de nomes de caminhos

Código-fonte: Lib/posixpath.py (para POSIX) e Lib/ntpath.py (para Windows).

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, ou qualquer objeto que implemente o protocolo `os.PathLike`.

Unlike a unix shell, Python does not do any automatic path expansions. Functions such as `expanduser()` and `expandvars()` can be invoked explicitly when an application desires shell-like path expansion. (See also the `glob` module.)

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

Alterado na versão 3.8: `exists()`, `lexists()`, `isdir()`, `isfile()`, `islink()` e `ismount()` agora retornam `False` em vez de levantar uma exceção para caminhos que contêm caracteres ou bytes não representáveis no nível de sistema de operacional.

`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 objeto caminho ou similar.

`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 objeto caminho ou similar.

`os.path.``commonpath`(paths)

  Retorna o subcaminho comum mais longo de cada nome de caminho na sequência paths. Levanta `ValueError` se path contiverem nomes de caminho absolutos e relativos, os paths estiverem em unidades diferentes ou se paths estiverem vazios. Ao contrário de `commonprefix()`, retorna um caminho válido.

  Disponibilidade: Unix, Windows.

  Novo na versão 3.5.

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

`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 objeto caminho ou similar.

`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 objeto caminho ou similar.

`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 objeto caminho ou similar.

`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 objeto caminho ou similar.

`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, `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 objeto caminho ou similar.

  Alterado na versão 3.8: Não usa mais `HOME` no Windows.

`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 objeto caminho ou similar.

`os.path.``getatime`(path)

  Retorna a hora do último acesso de path. O valor de retorno é um número de ponto flutuante dando 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.

`os.path.``getmtime`(path)

  Retorna a hora da última modificação de path. O valor de retorno é um número de ponto flutuante dando 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 objeto caminho ou similar.

`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 objeto caminho ou similar.

`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 objeto caminho ou similar.

`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 objeto caminho ou similar.

`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 objeto caminho ou similar.

`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 objeto caminho ou similar.

`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 objeto caminho ou similar.

`os.path.``ismount`(path)

  Retorna `True` se o nome de caminho path for um ponto de montagem: um ponto em um sistema de arquivos onde um sistema de arquivos diferente foi montado. No POSIX, a função verifica se o pai de path, `path/..`, está em um dispositivo diferente de path, ou se `path/..` e path apontam para o mesmo nó-i no mesmo dispositivo – isso deve detectar pontos de montagem para todas as variantes Unix e POSIX. Não é capaz de detectar confiavelmente montagens bind no mesmo sistema de arquivos. No Windows, uma raiz de letra de unidade e um UNC de compartilhamento são sempre pontos de montagem e, para qualquer outro caminho, `GetVolumePathName` é chamado para ver se é diferente do caminho de entrada.

  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 objeto caminho ou similar.

`os.path.``join`(path, *paths)

  Join one or more path components intelligently. The return value is the concatenation of path and any members of *paths with exactly one directory separator following each non-empty part except the last, meaning that the result will only end in a separator if the last part is empty. If a component is an absolute path, all previous components are thrown away and joining continues from the absolute path component.

  On Windows, the drive letter is not reset when an absolute path component (e.g., `r'\foo'`) is encountered. If a component contains a drive letter, all previous components are thrown away and the drive letter is reset. Note that since there is a current directory for each drive, `os.path.join("c:", "foo")` represents a path relative to the current directory on drive `C:` (`c:foo`), not `c:\foo`.

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

`os.path.``normcase`(path)

  Normaliza o estado de letras maiúsculas/minúsculas de um nome de caminho. No Windows, converte todos os caracteres do nome do caminho em minúsculas e também converte barras normais em barras invertidas. Em outros sistemas operacionais, retorna o caminho inalterado.

  Alterado na versão 3.6: Aceita um objeto caminho ou similar.

`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()`.

  Nota

  > On POSIX systems, in accordance with IEEE Std 1003.1 2013 Edition; 4.13 Pathname Resolution, if a pathname begins with exactly two slashes, the first component following the leading characters may be interpreted in an implementation-defined manner, although more than two leading characters shall be treated as a single character.

  Alterado na versão 3.6: Aceita um objeto caminho ou similar.

`os.path.``realpath`(path, *, strict=False)

  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).

  Por padrão, o caminho é avaliado até o primeiro componente que não existe, é um laço de link simbólico ou cuja avaliação levanta `OSError`. Todos esses componentes são anexados inalterados à parte existente do caminho.

  Alguns erros tratados dessa forma incluem “acesso negado”, “não é um diretório” ou “argumento inválido para função interna”. Assim, o caminho resultante pode estar ausente ou inacessível, ainda pode conter links ou laços e pode passar por diretórios não especificados.

  Esse comportamento pode ser modificado por argumentos nomeados:

  Se strict for `True`, o primeiro erro encontrado ao avaliar o caminho será levantado novamente. Em particular, `FileNotFoundError` é levantada se path não existir, ou outro `OSError` se ele estiver inacessível.

  Se strict for `os.path.ALLOW_MISSING`, erros diferentes de `FileNotFoundError` serão levantados novamente (como em `strict=True`). Portanto, o caminho retornado não conterá nenhum link simbólico, mas o arquivo nomeado e alguns de seus diretórios pais podem estar ausentes.

  Nota

  Esta função emula o procedimento do sistema operacional para tornar um caminho canônico, que difere ligeiramente entre o Windows e o UNIX em relação a como links e componentes de caminho subsequentes interagem.

  As APIs do sistema operacional tornam os caminhos canônicos conforme necessário, portanto, normalmente não é necessário chamar esta função.

  Alterado na versão 3.6: Aceita um objeto caminho ou similar.

  Alterado na versão 3.8: Links simbólicos e junções agora são resolvidos no Windows.

  Alterado na versão 3.9.23: O parâmetro strict foi adicionado.

  Alterado na versão 3.9.25 (unreleased): O valor `ALLOW_MISSING` para o parâmetro strict foi adicionado.

`os.path.``ALLOW_MISSING`

  Valor especial usado para o argumento strict em `realpath()`.

  Novo na versão 3.9.25 (unreleased).

`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. No Windows, `ValueError` é levantada quando path e start estão em unidades diferentes.

  start tem como padrão `os.curdir`.

  Disponibilidade: Unix, Windows.

  Alterado na versão 3.6: Aceita um objeto caminho ou similar.

`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 objeto caminho ou similar.

`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 objeto caminho ou similar.

`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 objeto caminho ou similar.

`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 objeto caminho ou similar.

`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, incluindo os dois pontos:

      >>> splitdrive("c:/dir")
      ("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:

      >>> splitdrive("//host/computer/dir")
      ("//host/computer", "/dir")

  Alterado na versão 3.6: Aceita um objeto caminho ou similar.

`os.path.``splitext`(path)

  Divida o nome do caminho path em um par `(root, ext)` de modo que `root + ext == path`, e a extensão, ext, esteja vazia ou comece com um ponto e contenha no máximo um período.

  Se o caminho não contiver extensão, ext será `''`:

      >>> splitext('bar')
      ('bar', '')

  Se o caminho contiver uma extensão, ext será definido para esta extensão, incluindo o ponto inicial. Observe que os períodos anteriores serão ignorados:

      >>> splitext('foo.bar.exe')
      ('foo.bar', '.exe')
      >>> splitext('/foo/bar.exe')
      ('/foo/bar', '.exe')

  Os períodos iniciais do último componente do caminho são considerados parte da raiz:

      >>> splitext('.cshrc')
      ('.cshrc', '')
      >>> splitext('/foo/....jpg')
      ('/foo/....jpg', '')

  Alterado na versão 3.6: Aceita um objeto caminho ou similar.

`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).