Просмотр кода страницы Макропрограммирование K3 в Python

[[Категория:Макро|*]]
[[Файл:Button2 py processed.png|128px|слева]]
===Общие принципы===

Команда macro в '''К3''' может запускать два типа файлов – макропрограмму '''k3''' (файл '''.mac''') и макропрограмму на '''Python''' (файл '''.py'''). Расширение файла показывает системе, какой интерпретатор использовать.

Также в '''К3''' есть возможность вставить блок кода на '''Python''' внутрь файла '''.mac'''. 
{{macro| Для вставки блока кода на языке '''Python''' необходимо воспользоваться конструкцией:
<syntaxhighlight lang="html">
 <?python
 …
 ?>
</syntaxhighlight>

Например так:

<syntaxhighlight lang="python" line highlight="3,9">
key_ecd=0;
//исключаем из анализа зависимости типа створки например шлегель unitcode=6900
<?python
import k3
key_elemcode=k3.Var("key_ecd")
elem_code=k3.GlobalVar("ElemCode")
if elem_code.value in ("6900",):
    key_elemcode.value=1
?>
if key_ecd==1 {
	goto end;
}
</syntaxhighlight>
}}
Для всех строчек кода внутри будет использоваться интерпретатор <code>python</code>.

===Библиотека, функции и команды. Ключевые слова===
Для использования функционала '''К3''' в программу на '''Python''' нужно импортировать специальную библиотеку '''Import k3'''

Все функции и команды '''K3''' вызываются как функции из этой библиотеки с использованием трёх основных принципов:
* Имя функции совпадает с именем команды, но обязательно должно быть написано в нижнем регистре;
* Все аргументы или ключевые слова передаются в функцию в том же порядке, как и при обычном вызове в макропрограмме;
* В Python нет специального обозначения для возвращения результата работы команды ('''#''' в макропрограмме). Поскольку команды – это тоже функции в Python, они возвращают значение обычным образом.
* Все функции К3 могут принимать на вход либо набор аргументов, либо список аргументов либо кортеж аргументов. Если на вход функции передан один список или один кортеж, то он будет "распакован", то есть функция примет элементы списка/кортежа как отдельные аргументы

Например, команда рисования линии, возвращающая ссылку на построенный объект

<code>#line1 '''line''' ''0 0 0 100 0 0'' done</code>

В python будет записываться как

<code>line1 = k3.'''line'''(''0, 0, 0, 100, 0, 0,'' k3.k_done)</code>

<code>k3.k_done</code> – это объект соответствующий ключевому слову <code>done</code>. Все ключевые слова записываются для использования в Python таким образом: <code>k3.k_<название></code>, где <code><название></code> — название ключевого слова.

Также аргументы могут быть переданы как список/кортеж, то есть запись

<code>line_par = [0, 0, 0, 100, 0, 0, k3.k_done]

line1 = k3.line(line_par)</code>

сработает так же, как предыдущая.

Учтите, что запись

<code>line_par = [0, 0, 0, 100, 0, 0]

line1 = k3.line(line_par, k3.k_done)</code>

уже вызовет ошибку, поскольку передан не один список, поэтому список не распаковывается, а считается первым аргументом, в качестве которого функция k3.line ожидает увидеть число - первую координату.

Ключевое слово для интерактивного ввода (то, что в макропрограмме записывалось знаком двоеточия ( : ), в Python запишется как <code>k3.k_interact</code>, например:

<code>k3.'''line'''(''0, 0, 0'', k3.k_interact, k3.k_done)</code>

построит линию от точки '''0''' до точки, введённой пользователем в интерактивном режиме.

{{Идея
|'''Функции К3, запущенные через библиотеку К3 в Python, всегда возвращают числа в формате с плавающей точкой (double). Поэтому часто для дальнейшего использования их нужно перевести в целое, например'''

<code>k3.'''getobjnum'''(k3.'''sysvar'''(''60'')) </code>

'''вернёт ошибку, поскольку функция''' <code>'''getobjnum'''</code> '''должна получать на вход целое число, а''' <code>k3.'''sysvar'''()</code> '''вернёт double. Необходимо писать так:'''

<code>k3.'''getobjnum'''('''int'''(k3.'''sysvar'''(''60'')))</code>
}}

===Переменные и массивы K3===
Все переменные, которые мы объявляем в коде на Python – это обычные переменные Python. Некоторые функции K3 требуют работы именно с переменными или массивами K3, например, функции '''objident''' и '''objgab3'''

<code>k3.'''objident'''(''<object>, <variable>'')</code>

<code>k3.'''objgab3'''(''<object>, <array>'')</code>

Здесь <code>''<variable>''</code> — это переменная k3, а <code>''<array>''</code> — массив К3 и именно такие объекты нужно передавать в функцию.

Переменная К3 в Python — это объект класса <code>k3.Var</code>, создаётся с помощью:

<code>varname = k3.Var(''<name>'')</code>

Где <code><name></code> — строка с именем переменной K3.

У этого объекта есть атрибут <code>''varname''.value</code>, который содержит значение этой переменной.

В результате, вызов функции '''objident''' будет выглядеть таким образом:

 varname = k3.Var(''‘obj1’'')
 k3.'''objident'''(k3.k_interact, ''varname'')

в результате ссылка на объект, выбранный пользователем в интерактивном режиме (ключ <code>interact</code>), будет присвоена переменной K3 с названием <code>''obj1''</code>, которой соответствует объект в Python с именем <code>''varname''</code>. Для того, чтобы добраться до этого объекта, используем обращение к атрибуту <code>value</code>

<code>k3.'''move'''(''varname''.value, k3.k_done, ''100, 0, 0'')</code>

Этой функцией мы сдвигаем объект, лежащий в переменной K3, на '''100''' по оси '''x'''

Массив K3 создаётся похожим образом:

<code>arrname = k3.'''VarArray'''(''<length>, <name>'')</code>

Здесь <code>''<length>''</code> — это длина будущего массива, а <code>''<name>''</code> — его имя в K3.

{{Идея
|'''Не забывайте, что хотя Python может работать с динамическими списками, массивы K3 – статические, то есть содержат ровно столько элементов, какая длина указана при создании.'''
}}

С точки зрения Python объект <code>VarArray</code> — это список объектов типа '''Var''', каждый из которых – один элемент массива, например

 for member in ''arrname'':
 	'''print'''(member.value)

выведет в консоль (в панель команд) значения всех элементов массива <code>arrname</code>

Аналогичным образом можно использовать и глобальные переменные и массивы, например:

<code>gl_var = k3.'''GlobalVar'''(''‘name’'')</code>

аналогично записи

 global
 name;

в K3, то есть объявляет глобальную переменную с именем name. В результате её значение можно получить <code>(gl_var.value)</code>, проверить, было ли оно раньше присвоено <code>(k3.'''isvardef'''(''‘name’''))</code> и так далее.

Учтите, что функция '''isvardef принимает не саму переменную, а её имя, то есть её аргумент должен быть строкой.

Работа с глобальными массивами осуществляется через <code>k3.'''GlobalVarArray'''</code>

===Получение параметров в макропрограмму (getpar)===
Для того, чтобы программа на python могла получить параметры макро, переданные через строку запуска, также как и в макропрограмме, нужно воспользоваться функцией '''getpar'''.

<code>income = k3.'''getpar'''()</code>

в результате переменной <code>''income''</code> будет присвоен список значений, которые переданы по значению (без ключа или с ключом ByVal) и переменных K3 для того, что передано по ссылке (с ключом ByRef), в которых будут находиться переданные значения. 

 val0 = ''income''[0].value
 val1 = ''income''[1].value
 …
 и т.д.

{{Идея|
В отличие от макропрограммы в Python при вызове '''getpar''' не объявляется явно количество значений, которые мы собираемся получить.
}}
{{#seo:
|title=Макропрограммирование К3 в Python {{!}} База знаний
|description=Это онлайн-руководство пользователя программ '''К3''', содержащее описание макропрограммирования в '''К3''' и её приложениях при помощи языка Python
|keywords=К3-Мебель, кз-мебель, k3-mebel, К3-Коттедж, кз-коттедж, k3-cottage, К3-Ship, кз-ship, k3-ship, инструкция, база знаний, online руководство, обучение, k3makro wiki, макро, макропрограммирование, макропрограммы, Python, питон, Питон
}}

=== Вызов сторонней макропрограммы (команда '''macro''') ===
Для вызова сторонней макропрограммы из скрипта на '''Python''' нужно передать в аргументы функции строку с путём и именем файла и список из передаваемых значений и ключей <code>byref</code> или <code>byval</code>

Например:

<code>k3.'''macro'''(‘my_macro.mac’, [k3.k_byref, k3_var1, k3.k_byval, var2], k3.k_done)</code>

Здесь первый параметр передаётся по ссылке (ключ <code>byref</code>), поэтому он должен быть переменной '''K3''', второй параметр передаётся по значению (ключ <code>byval</code>), поэтому это обычная переменная с некоторым значением.

{{Внимание| Версии программы до 09.10.2024 поддерживают только передачу параметров по ссылке (<code>byref</code>)! }}

{{Идея| Для вызова программы на макроязыке к3 можно использовать модуль '''macroForPy'''. В этом случае не приходится заботиться о передаче ключей (ключ <code>byref</code>). Достаточно вызвать функцию <code>runMacro</code> и передать ей на вход имя макроса и список аргументов. Именованный параметр <code>path</code> с значение по умолчанию папка <code>Proto</code> нужен только если вам требуется вызвать макрос из папки отличной от <code>Proto</code> или <code>userProto</code>.

{{python|
<syntaxhighlight lang="python" line highlight="1,14-16">
from macroForPy import runMacro
...
    def Draw(self):
        k3.setvarinst(1, "cZ_Fas", self.GetFasGabs()[1])
        box_mac = priceinfo(self._bxtype, "MacroFile", self._default_box_macro, 2)
        obj2 = k3.sysvar(60)
        box = k3.Var()
        x, y, z = self.GetPosition()
        k3.GlobalVar("BoxKType").value = self._bxtype
        if len(box_mac) == 0:
            box.value = super().Draw()
            self._object = box.value
        else:
            runMacro(
                box_mac, [self._w, self._d, self._h, self._prmater, self._prmatdv, 0]
            )

            objects = [] 
...
</syntaxhighlight>
}}
}}

=== Библиотека k3utils ===
''Файл'' '''k3utils.py'''

Данная библиотека содержит различные по области приложения полезные функции, которые могут пригодиться при написании макро для '''К3''' на '''Python'''

<code>'''check_furntype'''(''object, target'')</code>

Команда проверяет, является ли объект К3 <code>''object''</code> тем, что написано в <code>''target''</code>.

Например, <code>'''check_furntype'''(''panel, ‘panel’'')</code> вернёт '''True''', если в переменной <code>''panel''</code> действительно лежит ссылка не панель '''К3-Мебель'''.

Возможные значения <code>''target''</code>:
* '''‘panel’''' — мебельная панель
* '''‘profile’''' — мебельный профиль
* '''‘long’''' — длинномер
* '''‘accessory'''’ — комплектующий
* '''‘hand’''' — ручка
* '''‘leg’''' — опора
* '''‘guide’''' — направляющая

Проверка проводится по значению атрибута '''[[FurnType]]'''. При необходимости список доступных типов объектов можно расширить, для этого нужно пополнить словарь ключевых слов и проверочных строк <code>checks</code> в библиотеке.


<code>'''msgwin'''(''text_list, caption, button'')</code>

Команда выводит окно '''К3''' с текстом, записанным в списке <code>''text_list''</code> построчно, заголовком <code>''caption''</code> и надписью на кнопке <code>''button''</code>.


<code>'''errwin'''(''text'')</code>

Команда выводит сообщение с заданной строкой текста, заголовком '''«Ошибка»''' и кнопкой '''OK''' для закрытия.


<code>'''current_folder'''()</code>

Команда возвращает строку с полным путём к папке, в которой находится текущий открытый файл К3


<code>'''materials_from_subst'''(''subst'')</code>

Команда возвращает список с id материалов номенклатуры из подстановки с id равным <code>''subst''</code>


<code>'''putmsg_log'''(''message, level'')</code>

Выводит в консоль '''К3''' содержимое <code>''message''</code>.

Если <code>''message''</code> — список или кортеж — выводит его построчно

Если <code>''message''</code> — словарь, то выводит построчно пары '''Ключ Значение'''

Остальные типы <code>''message''</code> выводятся как есть

<code>''level''</code> — уровень сообщения '''putmsg'''. По умолчанию стоит '''2'''


<code>'''force_push_attr'''(''obj, name, value'')</code>

Функция обеспечивает у объекта '''К3''' <code>''obj''</code> наличие атрибута name с значением <code>''value''</code>.

Атрибут должен быть создан заранее.

Если у объекта не было этого атрибута, добавляет, если уже был, меняет значение на данное


<code>'''get_niche'''(''prompt'')</code>

Вызывает запрос на указание ниши с текстом запроса <code>''prompt''</code>

Возвращает '''None''', если от выбора ниши отказались

Если ниша была выбрана возвращает список в следующем порядке:
* '''0''' — ссылка на изделие или каркас, в котором выбрана ниша
* '''1, 2, 3''' — габариты ниши
* '''4, 5, 6, 7, 8, 9''' — панели, ограничивающие нишу в порядке '''Нижняя, Верхняя, Задняя, Передняя, Правая, Левая'''. Если какая-то из панелей отсутствует, в этом месте будет '''None'''

Если ниша была выбрана, то функция переносит '''ПСК''' в '''ЛСК''' ниши


<code>'''provide_carcase'''()</code>

Проверяет наличие разобранного каркаса.

Если есть, возвращает '''True'''. 

Если нет, но есть один собранный, разбирает его и возвращает '''True'''

Если есть несколько собранных, предлагает выбрать каркас для разбора и после выбора возвращает '''True'''

Если в сцене нет каркасов или несколько собранных, но пользователь отказался от выбора каркаса для разбора, возвращает '''False'''


<code>'''is_salon'''()</code>

Возвращает '''True''', если программа — '''К3-Мебель''' и комплект — '''Салон'''. В остальных случаях возвращает '''False'''


<code>'''acc_to_panel'''(''acc_list, panel'')</code>

Привязывает к панели <code>''panel''</code> комплектующие из списка <code>''acc_list''</code>


<code>'''k3_round'''(''value'')</code>

Возвращает полученное число <code>''value''</code>, округленное согласно текущим настройкам округления координат '''K3'''


<code>'''select_to_list'''()</code>

Возвращает список с объектами, которые в данный момент являются выбранными

===Пример программы для К3-Мебель на Python===
{{python|
<syntaxhighlight lang="python" line>
 # -*- coding: utf-8 -*-
 # Макро для поиска объектов с плохими записями в базе
 import k3	#Импортируем библиотеку функций и команд К3
 
 def Object_Is_Panel(obj):
 	'''Функция проверяет по атрибуту FurnType, является ли объект мебельной панелью'''
 	furntype = k3.getattr(obj, 'FurnType', '')		#Функция К3 getattr 
 	return furntype[:2]=='01' and not furntype[2:]=='0000'
 
 def Check_Panel_Material(obj):
 	'''Функция проверяет на корректность заданный для панели материал'''
 	if not Object_Is_Panel(obj):
 		return 1
 	priceid = k3.getattr(obj, 'PriceID', 0)
 	if priceid==0:
 		k3.putmsg('PriceID панели не задан или равен 0')	#Функция К3 putmsg 
 		return 0
 	if k3.priceinfo(priceid, 'Thickness', 0, 1)==0:	#Функция К3 priceifo 
 		k3.putmsg('Некорректный материал панели')
 		return 0
 	return 1
 
 k3.layers(k3.k_new, 'Possible_Errors')	#Функция К3 layers с ключом new
 object_number = int(k3.sysvar(62))	#sysvar(62) – количество объектов, но в Python добавляем int()
 errnum=0
 for current_number in range(object_number):
 	if not Check_Panel_Material (k3.getobjnums(current_number+1)):
 			k3.chprop(k3.k_layer, k3.k_partly, k3.getobjnums(current_number), k3.k_done, 'Possible_Errors')
 			errnum=errnum+1
 k3.putmsg(f'На слой Possible_Errors отправлено {errnum} объектов')
</syntaxhighlight>
}}
В основном теле программы создаётся новый слой командой '''layers''' с ключом '''new''', затем идёт перебор всех объектов функцией '''getobjnums'''. 

Заметьте, что функция '''getobjnums''' принимает в качестве аргумента номер объекта от '''1''' до '''sysvar(62)''', а счётчик в цикле '''range(object_number)''' в Python генерирует номера от '''0''' до '''object_number''', поэтому объекты нумеруем, добавляя к значению счётчика '''1'''.

Функция '''k3.putmsg()''' принимает на вход строку, поэтому можно использовать стандартное для Python форматирование строк.