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 UNIXntpath
para caminhos do Windowsmacpath
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çãobasename()
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. RetornaFalse
para links simbólicos quebrados. Em algumas plataformas, esta função pode retornarFalse
se a permissão não for concedida para executaros.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. RetornaTrue
para links simbólicos quebrados. Equivalente aexists()
em plataformas semos.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 ambienteHOME
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 embutidopwd
. Um~user
no início é procurado diretamente no diretório de senhas.On Windows,
HOME
andUSERPROFILE
will be used if set, otherwise a combination ofHOMEPATH
andHOMEDRIVE
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). RaiseOSError
if the file does not exist or is inaccessible.If
os.stat_float_times()
returnsTrue
, 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). RaiseOSError
if the file does not exist or is inaccessible.If
os.stat_float_times()
returnsTrue
, 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
). LevantaOSError
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 regularexistente
. Isso segue links simbólicos, entãoislink()
eisfile()
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órioexistente
. Isso segue links simbólicos, entãoislink()
eisdir()
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órioexistente
que é um link simbólico. SempreFalse
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 whetherpath/..
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 pathGetVolumePathName
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 unidadeC:
(c:foo
), e nãoc:\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
orbytes
(directly or indirectly through theos.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
eA/foo/../B
todos se tornemA/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, usenormcase()
.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 chamadaos.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 poros.fstat()
,os.lstat()
ouos.stat()
. Esta função implementa a comparação subjacente usada porsamefile()
esameopenfile()
.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çõesdirname()
ebasename()
.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 queroot + 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 asr'\\host\mount'
), if present, and rest the rest of the path (such asr'\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).