# MoXing常用操作的样例代码
#### 读写操作
- 读取一个OBS文件。
  例如读取"obs://bucket_name/obs_file.txt"文件内容，返回string（字符串类型）。
  ```
  import moxing as mox
  file_str = mox.file.read('obs://bucket_name/obs_file.txt')
  ```
  也可以使用打开文件对象并读取的方式来实现，两者是等价的。
  ```
  import moxing as mox
  with mox.file.File('obs://bucket_name/obs_file.txt', 'r') as f:
    file_str = f.read()
  ```
  
- 从文件中读取一行，返回string，以换行符结尾。同样可以打开OBS的文件对象。
  ```
  import moxing as mox
  with mox.file.File('obs://bucket_name/obs_file.txt', 'r') as f:
    file_line = f.readline()
  ```
  
- 从文件中读取所有行，返回一个list，每个元素是一行，以换行符结尾。
  ```
  import moxing as mox
  with mox.file.File('obs://bucket_name/obs_file.txt', 'r') as f:
    file_line_list = f.readlines()
  ```
  
- 以二进制模式读取一个OBS文件。
  例如读取"obs://bucket_name/obs_file.bin"文件内容，返回bytes（字节类型）。
  ```
  import moxing as mox
  file_bytes = mox.file.read('obs://bucket_name/obs_file.bin', binary=True)
  ```
  也可以使用打开文件对象并读取的方式来实现，两者是等价的。
  ```
  import moxing as mox
  with mox.file.File('obs://bucket_name/obs_file.bin', 'rb') as f:
    file_bytes = f.read()
  ```
  以二进制模式打开的文件也支持读取一行或者读取所有行，用法不变。
  
- 将字符串写入一个文件。
  例如将字符串"Hello World!"写入OBS文件"obs://bucket_name/obs_file.txt"中。
  ```
  import moxing as mox
  mox.file.write('obs://bucket_name/obs_file.txt', 'Hello World!')
  ```
  也可以使用打开文件对象并写入的方式来实现，两者是等价的。
  ```
  import moxing as mox
  with mox.file.File('obs://bucket_name/obs_file.txt', 'w') as f:
    f.write('Hello World!')
  ```
  ![](https://support.huaweicloud.com/devtool-modelarts/public_sys-resources/note_3.0-zh-cn.png)
  用写入模式打开文件或者调用mox.file.write时，如果被写入文件不存在，则会创建，如果已经存在，则会覆盖。
  
- 追加一个OBS文件。 例如将字符串"Hello World!"追加到"obs://bucket_name/obs_file.txt"文件中。
  ```
  import moxing as mox
  mox.file.append('obs://bucket_name/obs_file.txt', 'Hello World!')
  ```
  也可以使用打开文件对象并追加的方式来实现，两者是等价的。
  ```
  import moxing as mox
  with mox.file.File('obs://bucket_name/obs_file.txt', 'a') as f:
    f.write('Hello World!')
  ```
  用追加模式打开文件或者调用**mox.file.append**时，如果被写入文件不存在，则会创建，如果已经存在，则直接追加。
  当被追加的源文件比较大时，例如"obs://bucket_name/obs_file.txt"文件大小超过5MB时，追加一个OBS文件的性能比较低。
  ![](https://support.huaweicloud.com/devtool-modelarts/public_sys-resources/note_3.0-zh-cn.png)
  如果以写入模式或追加模式打开文件，当调用write方法时，待写入内容只是暂时的被存在的缓冲区，直到关闭文件对象（退出with语句时会自动关闭文件对象）或者主动调用文件对象的close()方法或flush()方法时，文件内容才会被写入。
  
 
#### 列举操作
- 列举一个OBS目录，只返回顶层结果（相对路径），不做递归列举。 例如列举"obs://bucket_name/object_dir"，返回该目录下所有的文件和文件夹，不会递归查询。
  假设"obs://bucket_name/object_dir"中有如下结构
  ```
  bucket_name
        |- object_dir
          |- dir0
            |- file00
          |- file1
  ```
  调用如下代码：
  ```
  import moxing as mox
  mox.file.list_directory('obs://bucket_name/object_dir')
  ```
  返回一个list：
  ```
  ['dir0', 'file1']
  ```
  
- 递归列举一个OBS目录，返回目录中所有的文件和文件夹（相对路径），并且会做递归查询。 假设obs://bucket_name/object_dir中有如下结构。
  ```
  bucket_name
        |- object_dir
          |- dir0
            |- file00
          |- file1
  ```
  调用如下代码：
  ```
  import moxing as mox
  mox.file.list_directory('obs://bucket_name/object_dir', recursive=True)
  ```
  返回一个list：
  ```
  ['dir0', 'dir0/file00', 'file1']
  ```
  
 
#### 创建文件夹操作
创建一个OBS目录（即OBS文件夹）。支持递归创建，即如果"sub_dir_0"文件夹不存在，也会自动被创建，如果已经存在，则不起任何作用。
```
import moxing as mox
mox.file.make_dirs('obs://bucket_name/sub_dir_0/sub_dir_1')
```
#### 查询操作
- 判断一个OBS文件是否存在，如果存在则返回**True** ，如果不存在则返回**False** 。
  ```
  import moxing as mox
  mox.file.exists('obs://bucket_name/sub_dir_0/file.txt')
  ```
  
- 判断一个OBS文件夹是否存在，如果存在则返回**True** ，如果不存在则返回**False** 。
  ```
  import moxing as mox
  mox.file.exists('obs://bucket_name/sub_dir_0/sub_dir_1')
  ```
  ![](https://support.huaweicloud.com/devtool-modelarts/public_sys-resources/note_3.0-zh-cn.png)
  由于OBS允许同名的文件和文件夹（Unix操作系统不允许），如果存在同名的文件和文件夹，例如"obs://bucket_name/sub_dir_0/abc"，当调用mox.file.exists时，不论abc是文件还是文件夹，都会返回True。
  
- 判断一个OBS路径是否为文件夹，如果是则返回**True** ，否则返回**False** 。
  ```
  import moxing as mox
  mox.file.is_directory('obs://bucket_name/sub_dir_0/sub_dir_1')
  ```
  ![](https://support.huaweicloud.com/devtool-modelarts/public_sys-resources/note_3.0-zh-cn.png)
  由于OBS允许同名的文件和文件夹（Unix操作系统不允许），如果存在同名的文件和文件夹，例如obs://bucket_name/sub_dir_0/abc，当调用mox.file.is_directory时，会返回True。
  
- 获取一个OBS文件的大小，单位为bytes。
  例如获取"obs://bucket_name/obs_file.txt"的文件大小。
  ```
  import moxing as mox
  mox.file.get_size('obs://bucket_name/obs_file.txt')
  ```
  
- 递归获取一个OBS文件夹下所有文件的大小，单位为bytes。
  例如获取"obs://bucket_name/object_dir"目录下所有文件大小的总和。
  ```
  import moxing as mox
  mox.file.get_size('obs://bucket_name/object_dir', recursive=True)
  ```
  
- 获取一个OBS文件或文件夹的stat信息，stat信息中包含如下信息。
  - length：文件大小。
  
  - mtime_nsec：创建时间戳。
  
  - is_directory：是否为目录。
  
  
  例如查询一个OBS文件"obs://bucket_name/obs_file.txt"，此文件地址也可以替换成一个文件夹地址。
  ```
  import moxing as mox
  stat = mox.file.stat('obs://bucket_name/obs_file.txt')
  print(stat.length)
  print(stat.mtime_nsec)
  print(stat.is_directory)
  ```
  
 
#### 删除操作
- 删除一个OBS文件。
  例如删除"obs://bucket_name/obs_file.txt"。
  ```
  import moxing as mox
  mox.file.remove('obs://bucket_name/obs_file.txt')
  ```
  
- 删除一个OBS目录，并且递归的删除这个目录下的所有内容。如果这个目录不存在，则会报错。
  例如删除"obs://bucket_name/sub_dir_0"下的所有内容。
  ```
  import moxing as mox
  mox.file.remove('obs://bucket_name/sub_dir_0', recursive=True)
  ```
  
 
#### 移动和复制操作
- 移动一个OBS文件或文件夹。移动操作本身是用"复制+删除"来实现的。
  - 一个OBS文件移动到另一个OBS文件，例如将"obs://bucket_name/obs_file.txt"移动到"obs://bucket_name/obs_file_2.txt"。
    ```
    import moxing as mox
    mox.file.rename('obs://bucket_name/obs_file.txt', 'obs://bucket_name/obs_file_2.txt')
    ```
    ![](https://support.huaweicloud.com/devtool-modelarts/public_sys-resources/note_3.0-zh-cn.png)
    移动和复制操作不可以跨桶，必须在同一个桶内操作。
    
  
  - 从OBS移动到本地，例如将"obs://bucket_name/obs_file.txt"移动到"/tmp/obs_file.txt"。
    ```
    import moxing as mox
    mox.file.rename('obs://bucket_name/obs_file.txt', '/tmp/obs_file.txt')
    ```
    
  
  - 从本地移动到OBS，例如将"/tmp/obs_file.txt"移动到"obs://bucket_name/obs_file.txt"。
    ```
    import moxing as mox
    mox.file.rename('/tmp/obs_file.txt', 'obs://bucket_name/obs_file.txt')
    ```
    
  
  - 从本地移动到本地，例如将"/tmp/obs_file.txt"移动到"/tmp/obs_file_2.txt"，该操作相当于**os.rename** 。
    ```
    import moxing as mox
    mox.file.rename('/tmp/obs_file.txt', '/tmp/obs_file_2.txt')
    ```
    
  
  
  所有的移动操作均可以操作文件夹，如果操作的是文件夹，那么则会递归移动文件夹下所有的内容。
  
- 复制一个文件。**mox.file.copy** 仅支持对文件操作，如果要对文件夹进行操作，请使用**mox.file.copy_parallel** 。
  - 从OBS复制到OBS，例如将"obs://bucket_name/obs_file.txt"复制到"obs://bucket_name/obs_file_2.txt"。
    ```
    import moxing as mox
    mox.file.copy('obs://bucket_name/obs_file.txt', 'obs://bucket_name/obs_file_2.txt')
    ```
    
  
  - 将OBS文件复制到本地，也就是下载一个OBS文件。例如下载"obs://bucket_name/obs_file.txt"到本地"/tmp/obs_file.txt"。
    ```
    import moxing as mox
    mox.file.copy('obs://bucket_name/obs_file.txt', '/tmp/obs_file.txt')
    ```
    
  
  - 将本地文件复制到OBS，也就是上传一个OBS文件，例如上传"/tmp/obs_file.txt"到"obs://bucket_name/obs_file.txt"。
    ```
    import moxing as mox
    mox.file.copy('/tmp/obs_file.txt', 'obs://bucket_name/obs_file.txt')
    ```
    
  
  - 将本地文件复制到本地，操作等价于**shutil.copyfile** ，例如将"/tmp/obs_file.txt"复制到"/tmp/obs_file_2.txt"。
    ```
    import moxing as mox
    mox.file.copy('/tmp/obs_file.txt', '/tmp/obs_file_2.txt')
    ```
    
   
- 复制一个文件夹。**mox.file.copy_parallel** 仅支持对文件夹操作，如果要对文件进行操作，请使用**mox.file.copy** 。
  - 从OBS复制到OBS，例如将obs://bucket_name/sub_dir_0复制到obs://bucket_name/sub_dir_1
    ```
    import moxing as mox
    mox.file.copy_parallel('obs://bucket_name/sub_dir_0', 'obs://bucket_name/sub_dir_1')
    ```
    
  
  - 将OBS文件夹复制到本地，也就是下载一个OBS文件夹。例如下载"obs://bucket_name/sub_dir_0"到本地"/tmp/sub_dir_0"。
    ```
    import moxing as mox
    mox.file.copy_parallel('obs://bucket_name/sub_dir_0', '/tmp/sub_dir_0')
    ```
    
  
  - 将本地文件夹复制到OBS，也就是上传一个OBS文件夹，例如上传"/tmp/sub_dir_0"到"obs://bucket_name/sub_dir_0"。
    ```
    import moxing as mox
    mox.file.copy_parallel('/tmp/sub_dir_0', 'obs://bucket_name/sub_dir_0')
    ```
    
  
  - 将本地文件夹复制到本地，操作等价于**shutil.copytree** ，例如将"/tmp/sub_dir_0"复制到"/tmp/sub_dir_1"。
    ```
    import moxing as mox
    mox.file.copy_parallel('/tmp/sub_dir_0', '/tmp/sub_dir_1')
    ```