Почему документация PyObjC такая плохая?

Этот ответ не будет очень полезным, но как разработчик я ненавижу делать документацию. Это проект с открытым исходным кодом, поэтому трудно найти людей, которые занимались бы документацией.

Том действительно все говорит. Многие проекты с открытым исходным кодом имеют преданных разработчиков и мало кто интересуется документированием. Этому не способствует тот факт, что стойки ворот могут смещаться ежедневно, а это означает, что документация не только должна создаваться, но и поддерживаться в рабочем состоянии.

Ответ Тома и Мартина определенно верен (практически в любом проекте с открытым исходным кодом вы обнаружите, что большинство участников особенно заинтересованы в развивающийся; не столько в частично связанных вопросах, таких как документация), но я не думаю, что ваш конкретный вопрос в конце хорошо впишется в документацию PyObjC.

NSThread.detachNewThreadSelector_toTarget_withObject_("queryController", self, None)

NSThread является частью Cocoa API и, как таковой, задокументировано в Apple, включая конкретный метод + detachNewThreadSelector:toTarget:withObject: (я бы связал его, но, по-видимому, у stackoverflow есть ошибки с его анализом). Вики-страница CocoaDev также есть статья.

Я не думаю, что для PyObjC было бы хорошей идеей попытаться задокументировать Какао, кроме нескольких основных примеров того, как его использовать из Python. Объяснение селекторов также, вероятно, выходит за рамки PyObjC, поскольку они тоже являются особенностью Objective-C, а не конкретно PyObjC.

Я согласен с тем, что этот учебник ошибочен, бросая случайный, необъяснимый код прямо перед вашими глазами. В нем представлены такие понятия, как пул автозапуска и пользовательские настройки по умолчанию, без объяснения, зачем они вам нужны («Пул автозапуска для управления памятью» вряд ли является объяснением).

Тем не менее ...

basically all I want to do is write Cocoa applications without having to learn ObjC.

Боюсь, что на данный момент вам буду понадобится базовое понимание ObjC, чтобы извлечь выгоду из любого языка, использующего Какао. PyObjC, RubyCocoa, Nu и другие - в лучшем случае ниши, и все они были разработаны людьми, хорошо знакомыми с тонкостями ObjC и Cocoa.

На данный момент вы получите наибольшую выгоду, если вы реально увидите эти мосты как полезные там, где действительно сияют языки сценариев, вместо того, чтобы пытаться создать на их основе целое приложение. Хотя этот имеет был выполнен (с LimeChat я использую приложение, написанное на RubyCocoa прямо сейчас), это редко и, вероятно, будет какое-то время.

Я наткнулся на хороший учебник по PyObjC / Cocoa:

http://lethain.com/entry/2008/aug/22/an-epic-introduction-to-pyobjc-and-cocoa/

All I want to do is create fairly simple Python applications with Cocoa GUI's.. Can anyone shed light on the horrible documentation, or point me at some tutorials that don't just give you huge blocks of code and assume you know what NSThread.detachNewThreadSelector_toTarget_withObject_("queryController", self, None) does..?

[...]

basically all I want to do is write Cocoa applications without having to learn ObjC.

Хотя я в основном согласен с ответом Soeren, я бы пошел еще дальше:

Пройдет много времени, если вообще когда-либо, прежде чем вы сможете использовать Какао без некоторого понимания Objective C. Какао не является абстракцией, построенной независимо от Objective C, она явно привязана к ней. Вы можете увидеть это в приведенном выше примере кода:

NSThread.detachNewThreadSelector_toTarget_withObject_("queryController", self, None) 

Это способ Python написать строку Objective C:

[NSThread detachNewThreadSelector:@selector(queryController:) toTarget:self withObject:nil];

Здесь важно отметить, что эту строку можно рассматривать двумя способами: (1) как строку Objective C или (2) как вызов структур Какао. Мы видим это как (1) по синтаксису. Мы видим это как (2), признавая, что NSThread - это структура Какао, которая предоставляет набор удобных функций. В этом случае эта конкретная структура Какао позволяет нам легко заставить объект что-то делать в новом потоке.

Но вот что самое интересное: фреймворк Cocoa здесь (NSThread) предоставляет нам эту удобную услугу способом, который явно привязан к языку, на котором был написан фреймворк. А именно, NSThread дал нам функцию, которая явно ссылается на «селекторы». . Фактически, селекторы - это название чего-то фундаментального о том, как работает Objective C.

Так вот в чем загвоздка. Какао по сути является продуктом Objective-C, и его создатели создали его с учетом Objective-C. Я не утверждаю, что невозможно перевести интерфейс функций Какао в форму, более естественную для других языков. Просто как только вы измените структуру Какао, чтобы перестать ссылаться на «селекторы», это больше не будет структура Какао. Это переведенная версия. И как только вы начнете идти по этому пути, я думаю, все станет по-настоящему беспорядочно. Вы пытаетесь не отставать от Apple, когда они обновляют Cocoa, возможно, вы столкнулись с некоторыми частями Cocoa, которые просто плохо переводятся на новый язык, как бы то ни было. Поэтому вместо этого такие вещи, как PyObjC, предпочитают напрямую предоставлять какао, таким образом, чтобы иметь очень четкую и простую корреляцию. Как говорится в документации:

In order to have a lossless and unambiguous translation between Objective-C messages and Python methods, the Python method name equivalent is simply the selector with colons replaced by underscores.

Конечно, это немного некрасиво, и это означает, что вам нужно что-то знать об Objective-C, но это потому, что альтернатива, если она действительно существует, не обязательно лучше.

Чтобы быть откровенным:

Если вы хотите быть эффективным программистом на Какао, вы должны изучить Objective-C. Конец истории.

Ни Python, ни Ruby не заменяют Objective-C через соответствующие мосты. Вы все еще должны понимать API-интерфейсы Objective-C, поведение, присущее классам, производным от NSObject, и многие другие детали Какао.

PyObjC и RubyCocoa - отличный способ получить доступ к функциям Python или Ruby из приложения Какао, включая создание приложения Какао в основном - если не полностью - на Python или Ruby. Но успех здесь основан на глубоком понимании какао и API Objective-C, из которых он состоит.

Я вообще ничего не знал об Objective C или Cocoa (но много о Python), но сейчас я пишу довольно сложное приложение на PyObjc. Как я узнал? Я взял Программирование какао для OSX и просмотрел всю книгу (довольно быстрый процесс), используя PyObjC. Просто игнорируйте все, что касается управления памятью, и все будет в порядке. Единственное предостережение: изредка приходится использовать декоратор вроде endSheetMethod (на самом деле я думаю, что это единственный, с которым я столкнулся):

@PyObjcTools.AppHelper.endSheetMethod
def alertEnded_code_context_(self, alert, choice, context):
    pass

Основная причина отсутствия документации для PyObjC заключается в том, что есть один разработчик (я), и, как большинство разработчиков, я не очень люблю писать документацию. Поскольку PyObjC для меня является побочным проектом, я стараюсь сосредоточиться на работе над функциями и исправлениями, потому что это для меня более интересно.

Лучший способ улучшить документацию - это добровольно участвовать в списке рассылки pyobjc-dev.

В стороне: список рассылки pythonmac-sig (см. Google) - отличный ресурс для получения помощи по Python на MacOSX (а не только PyObjC).