Fabric api что это
Fabric API
This page is about the Fabric API. For the Fabric Loader, see Fabric .
| Fabric | |
|---|---|
 | |
| Current developers | modmuss50 asiekierka et. al. |
| Version | 21w41a: 0.41.0 1.18 Exp Snap 1-7: 0.37..2-0.40.1 1.17.1: 0.41.0 1.17: 0.36.0 1.16.5: 0.40.6 1.16.4: 0.29.3 1.16.3: 0.25.0+build.415 1.16.2: 0.20.1+build.401 1.16.1: 0.18.0+build.387 1.16: 0.13.1+build.370 1.15.2: 0.28.5 1.15.1: 0.4.27+build.286 1.15: 0.4.27+build.286 1.14.4: 0.28.5 1.14.3: 0.3.0+build.198 1.14.2: 0.3.0+build.176 1.14.1: 0.3.0-pre+build.157a 1.14: 0.3.0-pre+build.156 |
| Supported Minecraft versions | 1.14-1.18 |
| URL | Link |
The Fabric API is an API used by Fabric mods to interact better with vanilla Minecraft. It is required by most but not all Fabric mods in the mods folder. It is highly modularized and has a few submods; this design allow mods that only use a fraction of the API to use that part instead of requiring players to install the entire API.
It currently supports 1.16.5 and 1.17.1 release versions, Snapshots (currently 21w41a) and Combat Test snapshots. Combat Test Snapshot support is displayed on the Fabric API and CraftPresence (which requires Fabric API) mod Curseforge pages.
Starting with snapshots (20w45a) builds have been dropped from file names; Fabric API versions will read «0.25.0» instead of «0.25.0 build 415».
As of 1.17 Pre-Release 1, 1.17 Fabric API builds (0.34.8 onwards, does not apply to prior 1.17 snapshot Fabric API builds) requires a Java 16 JDK build.
Fabric api что это
Essential hooks for modding with Fabric.
Fabric API is the library for essential hooks and interoperability mechanisms for Fabric mods. Examples include:
Also check out Fabric Loader, the (mostly) version-independent mod loader that powers Fabric. Fabric API is a mod like any other Fabric mod which requires Fabric Loader to be installed.
For support and discussion for both developers and users, visit the Fabric Discord server.
Using Fabric API to play with mods
Make sure you have install fabric loader first. More information about installing Fabric Loader can be found here.
To use Fabric API, download it from CurseForge, GitHub Releases or Modrinth.
The downloaded jar file should be placed in your mods folder.
Using Fabric API to develop mods
To setup a Fabric development environment, check out the Fabric example mod and follow the instructions there. The example mod already depends on Fabric API.
To include the full Fabric API with all modules in the development environment, add the following to your dependencies block in the gradle buildscript:
Alternatively, modules from Fabric API can be specified individually as shown below (including module jar to your mod jar):
Instead of hardcoding version constants all over the build script, Gradle properties may be used to replace these constants. Properties are defined in the gradle.properties file at the root of a project. More information is available here.
See something Fabric API doesn’t support, a bug or something that may be useful? We welcome contributions to improve Fabric API.
* The contributing guidelines are work in progress
Fabric API is designed to be modular for ease of updating. This also has the advantage of splitting up the codebase into smaller chunks.
Each module contains its own README.md * explaining the module’s purpose and additional info on using the module.
* The README for each module is being worked on; not every module has a README at the moment
jenyay.net
Софт, исходники и фото
Основы использования Fabric
Оглавление
Введение
Как известно, то, что обычный пользователь делает мышкой, повторяя одни и те же действия по 10 раз, программисты и, особенно, админы, делают скриптами. Инструментов и языков для написания скриптов существует огромное количество. Некоторые из них предназначены для определенных задач, например, на сборку и компиляцию программ, как Makefile и его последователи, другие являются более низкоуровневыми, например тот же bash. Промежуточное место я бы отвел для таких скриптовых языков как Python, Perl, Ruby. Преимущество последних в первую очередь в читаемости кода, когда нужно писать что-то большое, но в то же время, например, для работы с файлами, при работе с этими языками приходится писать больше кода, чем на том же bash.
Если мельком взглянуть на документацию Fabric, то складывается впечатление, что эта библиотека предназначена в первую очередь для работы на удаленном сервере при подключении к нему через SSH, однако, ее можно использовать и для локальных задач.
Лично я на данный момент Fabric использую для трех типов задач:
Разбираться с Fabric мы начнем с самого начала, т.е. с установки.
Установка
Установка под Linux не должна вызывать никаких затруднений. Достаточно написать в консоли
кому что больше нравится. И Fabric будет установлен вместе с необходимыми зависимостями.
А вот под Windows с установкой зависимостей могут возникнуть затруднения. Fabric использует библиотеку шифрования PyCrypto, которая, как правило, распространяется в исходных кодах и компилируется на месте при установке. Компиляция ее под Linux проблем не возникает, потому что редкая Linux-система (особенно система админа или программиста) не имеет компилятора C/C++.
Чтобы убедиться, что Fabric установлен, наберем в консоли команду
Если вы получите сообщение вида:
Fatal error: Couldn’t find any fabfiles!
Aborting.
Couldn’t find any fabfiles!
То значит, что все нормально и можно двигаться дальше.
Если вы пользуетесь Windows и вы получите сообщение о том, что команда fab не найдена, то убедитесь, что у вас добавлен путь до папки C:\Python27\Scripts\ или ее аналога для той версии Python, который вы используете, в переменную окружения PATH. В крайнем случае, вы всегда можете писать команду в виде
но просто fab писать удобнее.
Использование Fabric
Использование Fabric во многом напоминает использование Makefile, т.е. вы создаете в какой-то папке файл fabfile.py, в котором описываете задачи (как они описываются, мы рассмотрим чуть позже). Например, там может быть задача backup (для создания резервной копии) или deploy (для развертывания сайта) и т.д.
Затем в консоли вы запускаете команду
И Fabric выполняет нужные задачи. Можно указать несколько задач, тогда они будут выполнены последовательно, например, сначала создать резервную копию, а потом развернуть приложение:
В задачи можно передавать параметры. Параметры передаются после символа «:» после имени задачи. Пусть, например, мы можем указать путь до папки, куда делать резервную копию:
Если в параметрах нет пробелов, то кавычки можно не писать. Если параметров несколько, то они перечисляются через запятую. Но про передачу параметров мы еще поговорим.
Файл fabfile.py
Структура файла
Библиотека Fabric замечательна тем, что для ее использования не нужно разбираться с новым языком описания задач или каким-то новым синтаксисом, все задачи описываются на языке Python, возможно, с использованием вспомогательных средств Fabric. Так, например, для создания двух задач, которые были приведены выше в качестве примера, достаточно создать файл с именем fabfile.py (имя важно, хотя при желании его можно изменить, о чем будет сказано ниже) со следующим содержимым:
def backup ( ) :
print u ‘Run backup. ‘
print u ‘Ok’
def deploy ( ) :
print u ‘Run deploy. ‘
print u ‘Ok’
Кроме того, в файле профиля пользователя можно создать файл .fabricrc (под Linux путь будет выглядеть как
/.fabricrc), в котором задаются различные настройки по умолчанию. Если в этот файл добавить строку
то по умолчанию Fabric будет искать не файл fabfile.py, а файл my_fabfile.py.
Документирование задач
В таком виде подсказка уже полезна, но лучше все-таки еще добавить комментарии к каждой задаче. Чтобы их добавить, достаточно для каждой функции добавить описание в виде docstring:
def backup ( ) :
«»»
Создание резервной копии
«»»
print u ‘Run backup. ‘
print u ‘Ok’
def deploy ( ) :
«»»
Развертывание сайта mycoolsite.com
«»»
print u ‘Run deploy. ‘
print u ‘Ok’
В этом случае параметр —list выведет список задач следующим образом:
backup Создание резервной копии
deploy Развертывание сайта mycoolsite.com
На самом деле лучше не использовать в описаниях русские символы, поскольку в консоли под Windows они превратятся в кракозяблы (под Linux все будет работать нормально). Кроме того, не стоит писать очень длинные описания, поскольку они будут обрезаны до чуть больше чем 70 символов.
Понятно, что одни задачи могут вызывать другие задачи, кроме того внутри fabfile.py могут быть функции для внутреннего использования, попадание которых в список задач, выводимых с помощью параметра —list, нежелательно. Такие «внутренние» функции должны начинаться с символа «_». Так, например, функция _internal() из следующего прмиера fabfile.py не будет видна как задача:
def backup ( ) :
«»»
Создание резервной копии
«»»
print u ‘Run backup. ‘
print u ‘Ok’
def deploy ( ) :
«»»
Развертывание сайта mycoolsite.com
«»»
print u ‘Run deploy. ‘
print u ‘Ok’
def _internal ( ) :
pass
backup Создание резервной копии
deploy Развертывание сайта mycoolsite.com
Передача параметров
Выше мы уже говорили о том, что в задачи для Fabric мы можем передавать параметры, приведем несколько примеров. Для демонстрации мы будем использовать простую функцию, которая просто выводит переданный параметр:
def task ( param ) :
print param
Если мы забудем передать параметр, то вызов команды fab task приведет к ошибке:
Traceback (most recent call last):
File «/usr/local/lib/python2.7/dist-packages/Fabric-1.10.1-py2.7.egg/fabric/main.py», line 743, in main
*args, **kwargs
File «/usr/local/lib/python2.7/dist-packages/Fabric-1.10.1-py2.7.egg/fabric/tasks.py», line 424, in execute
results[‘ ‘] = task.run(*args, **new_kwargs)
File «/usr/local/lib/python2.7/dist-packages/Fabric-1.10.1-py2.7.egg/fabric/tasks.py», line 174, in run
return self.wrapped(*args, **kwargs)
TypeError: task() takes exactly 1 argument (0 given)
Если мы укажем значение параметра, то все будет работать, как положено:
$ fab task:»Hello world!»
Аналогичного результата мы добьемся, если будем указывать имя параметра:
$ fab task:param=»Hello world!»
Как и везде в языке Python, можно использовать значения параметров по умолчанию:
def task ( param = False ) :
print param
В этом случае значение параметра можно не передавать:
Если же задача функция принимает два и более значений, то параметры передаются через запятую. Например:
Главное тут не ошибиться и не добавить после запятой пробел, иначе второй параметр будет воспринят, как имя другой команды:
$ fab task:»Hello», «World»
Warning: Command(s) not found:
World
Как видно из предыдущей ошибки, Fabric позволяет одной командой запускать сразу несколько задач, которые будут выполняться последовательно.
def task1 ( ) :
print «Task 1»
def task2 ( ) :
print «Task 2»
Но если одна из них завершится с ошибкой, то следующая задача выполнена не будет.
def task1 ( ) :
raise Exception
def task2 ( ) :
print «Task 2»
Task 1
Traceback (most recent call last):
File «/usr/local/lib/python2.7/dist-packages/Fabric-1.10.1-py2.7.egg/fabric/main.py», line 743, in main
*args, **kwargs
File «/usr/local/lib/python2.7/dist-packages/Fabric-1.10.1-py2.7.egg/fabric/tasks.py», line 424, in execute
results[‘ ‘] = task.run(*args, **new_kwargs)
File «/usr/local/lib/python2.7/dist-packages/Fabric-1.10.1-py2.7.egg/fabric/tasks.py», line 174, in run
return self.wrapped(*args, **kwargs)
File «/media/Data/Workdir/Черновики/В процессе/Fabric/__attach/examples/03/fabfile.py», line 5, in task1
raise Exception
Exception
Теперь, когда мы рассмотрели способы запуска задач, перейдем к рассмотрению того, какие возможности нам предоставляет библиотека Fabric и ее модули. Внутри функций-задач мы можем использовать любые функции Python, в том числе и для копирования, удаления, переименования файлов и т.д. Также в Python есть средства для запуска программ. Но давайте посмотрим, какие функции нам предоставляет Fabric для облегчения работы на локальной компьютере и на удаленном сервере.
Использование Fabric на локальном компьютере
Знакомство с Fabric у меня началось с того, что я начал использовать эту библиотеку в качестве замены команды make и Makefile. Когда-то давно для сборки OutWiker использовался обычный Makefile. Например, команда make win собирала версию под Windows, а команда make deb делала deb-пакет под Linux’ы на основе Debian.
В результате Makefile по-прежнему используется, но только как часть сборки deb-пакетов под Linux, в остальном везде используется Fabric.
Рассмотрим пример, в котором будут выводиться рабочие директории с помощью функции стандартной библиотеки os.getpwd() и с помощью команды pwd консоли (для выполнения команды pwd будет использоваться вышеупомянутая функция local:
Результат в моем случае выглядит так (понятно, что у вас директории будут называться иначе):
jenyay@jenyay-desktop:/media/Data/Workdir/Черновики/В процессе/Fabric/__attach/examples/04$ fab task
**** Before ‘with’ operator
/media/Data/Workdir/Черновики/В процессе/Fabric/__attach/examples/04
[localhost] local: pwd
/media/Data/Workdir/Черновики/В процессе/Fabric/__attach/examples/04
**** Inside ‘with’ operator
/media/Data/Workdir/Черновики/В процессе/Fabric/__attach/examples/04
[localhost] local: pwd
/home/jenyay
**** After ‘with’ operator
/media/Data/Workdir/Черновики/В процессе/Fabric/__attach/examples/04
[localhost] local: pwd
/media/Data/Workdir/Черновики/В процессе/Fabric/__attach/examples/04
Разумеется, внутри функции local можно выполнять что-то более полезное. Например, в fabfile проекта OutWiker в задаче win, с помощью которой создается сборка OutWiker под Windows, можно найти такие строки:
На момент написания этих строк fabfile проекта OutWiker из модуля fabric.api используются только функции lcd и local.
Использование Fabric для взаимодействия с удаленным сервером
Настройка удаленного интерпретатора
Fabric удобно использовать на локальном компьютере, но больше всего возможностей эта библиотека предоставляет для работы по сети на удаленных серверах. Все возможности библиотеки в этой статье мы не рассмотрим, но, чтобы понять принцип работы, поговорим о некоторых из них.
Для работы на удаленном сервере существуют аналоги локальных функций lcd и local, это функции cd и run соответственно. Чтобы научиться подключаться к серверу, сделаем fabfile с одной задачей, которая просто выполняет команду ls на сервере, чтобы вывести список файлов в домашней директории.
В простейшем случае скрипт будет такой, но нужно заранее предупредить, что он может не сработать:
from fabric. api import run
def runls ( ) :
run ( «ls» )
Как видите, в скрипте мы не задаем никакого адреса (хотя мы может это сделать, и воспользуемся этой возможностью позже). Если мы теперь выполним команду fab runls, то Fabric сначала попросит ввести адрес, куда мы должны подключиться, а затем результат уже будет зависеть от настроек удаленного сервера. Далее приведен вывод команды fab runls при подключении к удаленному хранилищу по локальной сети:
No hosts found. Please specify (single) host string for connection: 192.168.100.10
[192.168.100.10] run: ls
[192.168.100.10] Passphrase for private key:
[192.168.100.10] out: Distrib VirtualBox VMs music projects Кино Фото
[192.168.100.10] out: Downloads backup photo temp Книги
[192.168.100.10] out:
Done.
Disconnecting from 192.168.100.10. done.
Но вполне может случиться и такая ошибка:
No hosts found. Please specify (single) host string for connection: 192.168.100.10
[192.168.100.10] run: ls
[192.168.100.10] Passphrase for private key:
[192.168.100.10] Login password for ‘jenyay’:
[192.168.100.10] out: sh: /bin/bash: not found
[192.168.100.10] out:
Fatal error: run() received nonzero return code 127 while executing!
Aborting.
Disconnecting from 192.168.100.10. done.
run() received nonzero return code 127 while executing!
Указать путь до интерпретатора можно разными способами. Во-первых, можно воспользоваться параметром командной строки —shell:
No hosts found. Please specify (single) host string for connection: 192.168.100.10
[192.168.100.10] run: ls
[192.168.100.10] Passphrase for private key:
[192.168.100.10] out: Distrib VirtualBox VMs music projects Кино Фото
[192.168.100.10] out: Downloads backup photo temp Книги
[192.168.100.10] out:
Done.
Disconnecting from 192.168.100.10. done.
Поскольку на данном сервере не установлен интерпретатор bash, я воспользовался интерпретатором sh.
Изучаем инструмент администрирования Fabric
Выполнение повседневных операций на большом количестве *nix-систем становится все более актуальной задачей. Количество серверов растет. Если вручную отдавать одну и ту же команду нескольким системам и отслеживать результат выполнения, то можно потратить уйму времени. Сегодня рассмотрим возможности Fabric, позволяющего выполнить задачу одновременно на большом количестве систем.
Начнем с основ
За последние несколько лет для *nix разработано, наверное, десяток различных систем управления конфигурациями (Chef, Puppet, CFEngine. ), разных по назначению и сложности. Но объединяет их одно — они не всегда подходят для одноразовых операций на уже работающих серверах или для несложных заданий. Согласитесь, чтобы выполнить определенную проверку, занимающую одну-две команды, придется писать манифест или сookbooks. Это долго и неудобно. Иногда быстрее полученную информацию проанализировать визуально, чем поручить разбор машине. Вот как раз здесь стоит присмотреться к Fabric, позволяющему выполнить любые задачи администрирования, запуская команды параллельно на любом количестве систем.
Для работы Fabric не требуется какого-либо дополнительного ПО. На управляемых системах необходим лишь работающий SSH-сервер. Имея навыки программирования на Python, можно создавать достаточно сложные примеры, обрабатывать вывод и ошибки. Здесь администратор практически ничем не ограничен. Поэтому вполне можно использовать Fabric вместо системы управления конфигурациями. Хотя, признаюсь, это не всегда удобно, тут придется найти баланс. Все-таки Python — это более общий язык, и, усложняя задачу, можем просто увязнуть в программировании.
Проект не предоставляет никаких заготовок наподобие Chef Cookbooks, потому что задачи здесь проще. В этом нет смысла. Хотя пользователи сами выкладывают в интернет готовые скрипты и расширения (их очень много на github.com), которые можно использовать в качестве базы для своих проектов. Например,проект Fabtools расширяет стандартный API Fabric функциональностью для работы с PostgreSQL, MySQL, Crontab, Node.js, nginx, OpenVZ, Redis, Postfix, deb/rpm-пакетами и другим. Проще показать все на примерах.
Знакомимся
Установка Fabric проблем не вызывает, тем более нужный пакет уже имеется в репозитории большинства дистрибутивов Linux. В Ubuntu/Debian и производных команда проста:
Вместе с Fabric будет установлен модуль paramiko, используемый в Python для работы с SSH. Для установки последней версии ставим через PIP:
Результат выполнения команды на нескольких серверах
Хакер #182. Все о Bitcoin
В принципе, минимум автоматизации уже есть, вместо нескольких консолей мы можем выполнять все действия в одной, отдавая команды сразу нескольким системам. Но это не все. Большинство операций администрирования редко выполняются одной командой, поэтому админы и придумали скрипты, в которых прописано все что нужно. Fabric позволяет использовать специальный файл, выполняющий все нужные действия.
Параметры командной строки утилиты fab
Командный файл Fabric
Здесь кроется главное отличие от скриптов: нельзя просто вызвать все задачи, прописанные в файле, указав что-то вроде «fab *». Имя задачи указывается обязательно. Так администратор подстраховывается от возможных ошибок. Хотя никто не мешает создать задачу, которая будет запускать все остальные задачи, и затем в строке запуска указать только ее. Вся информация из fabfile, в том числе пути, просто импортируются на время исполнения, по окончании все данные очищаются. Те, кто уже программировал на Python, найдут при создании и использовании fabfile много знакомого.
В результате получим все задачи, описанные в файле fabfile.py, находящемся в текущем каталоге.
Список команд в fabfile
Поэтому при работе с Fabric удобнее разделять скрипты не по файлам, а по каталогам, давая им понятное название. Внутри файл fabfile.py. Затем просто переходим в нужный каталог и даем команду для запуска. Для определенных задач в fabfile.py потребуются специфические функции, описанные в fabric.api. Их немного, импорт стандартен для Python.
Полный список доступен в документации или в файле /usr/share/pyshared/fabric/api.py. Чтобы их не запоминать, чаще всего импортируют сразу все.
Каких-либо проблем такой подход не вызывает.
Встроенные переменные Fabric
В Fabric предусмотрен ряд договоренностей, которые призваны упростить работу. Среди них более 50 встроенных переменных, полный список которых доступен в документации. Некоторые параметры уже заданы, значения других по умолчанию пусты, их при необходимости указывает сам пользователь. Установить или переопределить переменные можно непосредственно в командной строке, в fabfile или в специальном пользовательском файле
/.fabricrc.
Приоритет при совпадении названия переменной может быть разный и нередко зависит от самой переменной. Например, пароль, заданный в командной строке, переопределяет то, что записано в fabricrc (он считывается первым) и в fabfile (перекрывает fabricrc). Такое поведение обычно для большинства переменных. А вот список узлов определяется с точностью наоборот (подробнее рассмотрим далее). В самом файле переменные могут быть видимыми глобально или привязаны к определенному контексту/блоку.
Например, переменные user и password позволяют задать учетную запись для подключения к узлу:
В fabfile для установки встроенных переменных применяются два метода. Если нужно задать параметр глобально, то используется переменная env.[параметр]. Например, пользователь, пароль для подключения, разрешим параллельное выполнение заданий, установим рабочий каталог и уровень вывода ошибок:
В том случае, когда переменная переопределяется временно, на период текущей задачи используется инструкция settings:
С изучения встроенных переменных и нужно начать знакомство с Fabric, их много, а с каждой новой версией добавляются новые.
Пользовательские переменные Fabric
Конечно, сам пользователь может создавать свои переменные, указывая их в файле или в командной строке. Классический пример: создадим функцию, которая выводит «Hello world».
Имя функции hello и есть задача Fabric. Запустим с указанием задачи:
Но можно и переопределить переменную, указав свое значение:
В Fabric передаваемые аргументы доступны всем задачам (per-task arguments). Если аргументов несколько, их разделяют запятыми. В этом случае используется позиционирование, то есть они распределяются по параметрам по порядку. Хотя лучше сразу их именовать в строке вызова (name=][akep), для привязки аргумента конкретной задаче используется двоеточие (hello:name=][akep). Причем есть особенность — задачу можно вызвать несколько раз. То есть не нужно ее запускать несколько раз с разными аргументами, можно сразу указать их.
Все эти особенности следует знать и учитывать при составлении и использовании fabfile.
Хосты, хосты
Задачи, для которых не указаны узлы, всегда выполняются на локальной системе и запускаются один раз. Так как Fabric применяется для параллельного выполнения задач на нескольких удаленных системах, реализовано несколько способов их указать при запуске скрипта. Список узлов задается как глобально (то есть для всех выполняемых задач), так и для конкретной задачи. Один из вариантов глобальной установки мы уже рассматривали в примерах выше, это аргумент «-H host» команды fab.
Список узлов для всех задач в fabfile традиционно задается при помощи глобальной переменной env.hosts:
Задачи будут запущены только на оставшихся двух узлах. Чтобы указать список узлов, видимых в пределах определенной задачи, используется питоновский декоратор (decorator) @hosts:
Запись аналогична и такому вызову:
В этом случае узлы, указанные в env.hosts, будут видны только в пределах задачи test. Такой подход применяется, если системы имеют разное назначение или ОС. А значит, и задачи или отдельные команды должны различаться. Но есть более удобный и наглядный вариант — роли, устанавливаемые при помощи env.roledefs и позволяющие сгруппировать системы.
Когда роли определены, обратиться к ним можно, используя питоновские декораторы.
Специальный декоратор @parallel позволяет запустить определенное задание одновременно на нескольких системах.
Декоратор @serial, наоборот, указывает всегда выполнять блок последовательно, игнорируя параметры командной строки и значение env.parallel.
Операции, доступные в Fabric
Теперь самое время разобрать операции (fabric.operations), которые Fabric позволяет выполнить. Полный список приведен в документации API проекта. Остановлюсь лишь на наиболее часто используемых:
Остальные также проще объяснить на примере. Нам нужно развернуть зеркало Apache2 на двух узлах, скопировав на него файлы с текущего. Для установки веб-сервера используем пакетный менеджер и перенесем все файлы из локального каталога /var/www на удаленные системы.
Развертываем веб-сервер средствами Fabric
Заключение
Как видим, Fabric — это одновременно простой и функциональный способ автоматизации, позволяющий выполнить любые задачи на нескольких системах, прилагая минимум усилий. В условиях постоянного роста количества подчиненных серверов этот инструмент является оптимальным для одиночных команд или несложных операций. А имея навыки программирования на Python, можно создавать более сложные скрипты на любой случай.