In OS X (tested in 10.8 and higher), it is possible to add a file attachment (like an email or a PDF file) in an already created or in-creation event by drag-and-dropping it into the event (EDIT: or event by selecting Add attachment/file).
A similar question was asked in 2013. According to the Mac Developer Libary, there is no place to store a file in EKCalendarItem or EKEvent. Still, Apple does it.
Does the Calendar app use the notes property in some way to store such file? Or does it upload the file to iCloud and link the file in the event to it?
There is no single answer to your question. It depends on the server (Fruux, iCloud, Exchange, Yahoo, ...), client version etc.
There is a simple answer to this: Can I attach files using the EventKit API? No, you can't. EventKit functionality is very limited. The 'notes' property maps to the (first or last? ...) iCalendar description property.
For iCloud and OSX server the OSX/iOS client should do CalDAV managed attachments. For servers not supporting this, the client might inline the attachments in iCalendar attachments. But if I remember right there are also cases in which the client keeps the attachment just local and refers to it via a file: URL in the ATTACH property.
Summary: If you want to attach files to iCloud (or other CalDAV servers), you need to implement a CalDAV client.