python-aternos/docs/howto/files.md

How-To 4: Files

Intro

In python-aternos, all files on your Minecraft server are represented as atfile.AternosFile objects.

They can be accessed through atfm.FileManager instance, let's assign it to fm variable:

>>> fm = serv.files()

List directory contents

>>> root = fm.list_dir('/')
[<python_aternos.atfile.AternosFile object at 0x7f1b0...>, ...]

Get file by its path

>>> myfile = fm.get_file('/server.properties')
<python_aternos.atfile.AternosFile object at 0x7f1b0...>

File info

AternosFile object can point to both a file and a directory and contain almost the same properties and methods. (So it's more correct to call it "Object in the server's filesystem", but I chose an easier name for the class.)

• path - Full path to the file including leading slash and without trailing slash.
• name - Filename with extension without leading slash.
• dirname - Full path to the directory which contains the file without trailing slash.
• is_file and is_dir - File type in boolean.
• ftype - File type in FileType enum value:
  • FileType.file
  • FileType.dir and FileType.directory
• size - File size in bytes, float.
  0.0 for directories and -1.0 when an error occurs.
• deleteable, downloadable and editable are explained in the next section.

File

>>> f = root[5]

>>> f.path
'/server.properties'
>>> f.name
'server.properties'
>>> f.dirname
''

>>> f.is_file
False
>>> f.is_dir
True

>>> from python_aternos import FileType
>>> f.ftype == FileType.file
True
>>> f.ftype == FileType.directory
False

>>> f.size
1240.0

>>> f.deleteable
False
>>> f.downloadable
False
>>> f.editable
False

Directory

>>> f = root[2]

>>> f.path
'/config'
>>> f.name
'config'
>>> f.dirname
''

>>> f.is_file
False
>>> f.is_dir
True

>>> from python_aternos import FileType
>>> f.ftype == FileType.file
False
>>> f.ftype == FileType.directory
True
>>> f.ftype == FileType.dir
True

>>> f.size
0.0

>>> f.deleteable
False
>>> f.downloadable
True
>>> f.editable
False

Methods

• get_text returns the file content from the Aternos editor page (opens when you click on the file on web site).
• set_text is the same as "Save" button in the Aternos editor.
• get_content requests file downloading and returns file content in bytes (not str).
  If it is a directory, Aternos returns its content in a ZIP file.
• set_content like set_text, but takes bytes as an argument.
• delete removes file.
• create creates a new file inside this one
  (if it's a directory, otherwise throws RuntimeWarning).

Deletion and downloading rejection

In Aternos Files tab, some files can be removed with a red button, some of them is protected.
You can check if the file is deleteable this way:

>>> f.deleteable
False

delete() method will warn you if it's undeleteable, and then you'll probably get FileError because of Aternos deletion denial.

The same thing with downloadable.

>>> f.downloadable
True

get_content() will warn you if it's undownloadable. And then you'll get FileError.

And editable means that you can click on the file in Aternos "Files" tab to open editor. get_text() will warn about editing denial.

Creating files

Calling create method only available for directories (check it via f.is_dir).
It takes two arguments:

• name - name of a new file,
• ftype - type of a new file, must be FileType enum value:
  • FileType.file
  • FileType.dir or FileType.directory

For example, let's create an empty config for some Forge mod, I'll call it "testmod".

# Import enum
from python_aternos import FileType

# Get configs directory
conf = fm.get_file('/config')

# Create empty file
conf.create('testmod.toml', FileType.file)

Editing files

Let's edit ops.json. It contains operators nicknames, so the code below is the same as Players API.

import json
from python_aternos import Client

at = Client.from_credentials('username', 'password')
serv = at.list_servers()[0]

fm = serv.files()
ops = fm.get_file('/ops.json')

# If editable
use_get_text = True

# Check
if not ops.editable:

    # One more check
    if not ops.downloadable:
        print('Error')
        exit(0)

    # If downloadable
    use_get_text = False

def read():

    if use_get_text:
        return ops.get_text()
    else:
        return ops.get_content().decode('utf-8')

def write(content):

    # set_text and set_content
    # uses the same URLs,
    # so there's no point in checking
    # if the file is editable/downloadable

    # Code for set_text:
    #ops.set_text(content)

    # Code for set_content:
    # Convert the str to bytes
    content = content.encode('utf-8')
    # Edit
    ops.set_content(content)

# ops.json contains an empty list [] by default
oper_raw = read()

# Convert it to a Python list
oper_lst = json.loads(oper_raw)

# Add an operator
oper_lst.append('DarkCat09')

# Convert back to JSON
oper_new = json.dumps(oper_lst)

# Write
ops.write(oper_new)